api.txt

-------------
4. API access
-------------

The API allows other applications running on the same system to get p0f's
current opinion about a particular host. This is useful for integrating it with
spam filters, web apps, and so on.

Clients are welcome to connect to the unix socket specified with -s using the
SOCK_STREAM protocol, and may issue any number of fixed-length queries. The
queries will be answered in the order they are received.

Note that there is no response caching, nor any software limits in place on p0f
end, so it is your responsibility to write reasonably well-behaved clients.

Queries have exactly 21 bytes. The format is:

  - Magic dword (0x50304601), in native endian of the platform.

  - Address type byte: 4 for IPv4, 6 for IPv6.

  - 16 bytes of address data, network endian. IPv4 addresses should be
    aligned to the left.

To such a query, p0f responds with:

  - Another magic dword (0x50304602), native endian.

  - Status dword: 0x00 for 'bad query', 0x10 for 'OK', and 0x20 for 'no match'.

  - Host information, valid only if status is 'OK' (byte width in square
    brackets):

    [4]  first_seen  - unix time (seconds) of first observation of the host.

    [4]  last_seen   - unix time (seconds) of most recent traffic.

    [4]  total_conn  - total number of connections seen.

    [4]  uptime_min  - calculated system uptime, in minutes. Zero if not known.

    [4]  up_mod_days - uptime wrap-around interval, in days.

    [4]  last_nat    - time of the most recent detection of IP sharing (NAT,
                       load balancing, proxying). Zero if never detected.

    [4]  last_chg    - time of the most recent individual OS mismatch (e.g.,
                       due to multiboot or IP reuse).

    [2]  distance    - system distance (derived from TTL; -1 if no data).

    [1]  bad_sw      - p0f thinks the User-Agent or Server strings aren't
                       accurate. The value of 1 means OS difference (possibly
                       due to proxying), while 2 means an outright mismatch.

                       NOTE: If User-Agent is not present at all, this value
                       stays at 0.

    [1]  os_match_q  - OS match quality: 0 for a normal match; 1 for fuzzy
                       (e.g., TTL or DF difference); 2 for a generic signature;
                       and 3 for both.

    [32] os_name     - NUL-terminated name of the most recent positively matched
                       OS. If OS not known, os_name[0] is NUL.

                       NOTE: If the host is first seen using an known system and
                       then switches to an unknown one, this field is not
                       reset.

    [32] os_flavor   - OS version. May be empty if no data.

    [32] http_name   - most recent positively identified HTTP application
                       (e.g. 'Firefox').

    [32] http_flavor - version of the HTTP application, if any.

    [32] link_type   - network link type, if recognized.

    [32] language    - system language, if recognized.