{"id":13439490,"url":"https://github.com/DNS-OARC/dnscap","last_synced_at":"2025-03-20T08:31:14.256Z","repository":{"id":3847595,"uuid":"4931801","full_name":"DNS-OARC/dnscap","owner":"DNS-OARC","description":"Network capture utility designed specifically for DNS traffic","archived":false,"fork":false,"pushed_at":"2025-03-14T14:12:11.000Z","size":1578,"stargazers_count":280,"open_issues_count":15,"forks_count":59,"subscribers_count":32,"default_branch":"develop","last_synced_at":"2025-03-18T10:47:57.266Z","etag":null,"topics":["c","dns","packet-capture","pcap"],"latest_commit_sha":null,"homepage":"https://www.dns-oarc.net/tools/dnscap","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DNS-OARC.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":"https://www.dns-oarc.net/donate"}},"created_at":"2012-07-06T22:17:06.000Z","updated_at":"2025-03-14T14:12:15.000Z","dependencies_parsed_at":"2024-01-07T22:50:08.958Z","dependency_job_id":"9dc4c457-cb65-4f53-9aa5-17dd801e949d","html_url":"https://github.com/DNS-OARC/dnscap","commit_stats":{"total_commits":451,"total_committers":25,"mean_commits":18.04,"dds":0.5388026607538803,"last_synced_commit":"5a9a9480ded1b71d5c423907559a1111c1c1a7b7"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DNS-OARC%2Fdnscap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DNS-OARC%2Fdnscap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DNS-OARC%2Fdnscap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DNS-OARC%2Fdnscap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DNS-OARC","download_url":"https://codeload.github.com/DNS-OARC/dnscap/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244577724,"owners_count":20475352,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","dns","packet-capture","pcap"],"created_at":"2024-07-31T03:01:14.336Z","updated_at":"2025-03-20T08:31:14.247Z","avatar_url":"https://github.com/DNS-OARC.png","language":"C","funding_links":["https://www.dns-oarc.net/donate"],"categories":["C"],"sub_categories":[],"readme":"# dnscap\n\n[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=dns-oarc%3Adnscap\u0026metric=bugs)](https://sonarcloud.io/summary/new_code?id=dns-oarc%3Adnscap) [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=dns-oarc%3Adnscap\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=dns-oarc%3Adnscap)\n\n`dnscap` is a network capture utility designed specifically for DNS traffic.\nIt produces binary data in `pcap(3)` and other format. This utility is similar\nto `tcpdump(1)`, but has a number of features tailored to DNS transactions\nand protocol options. DNS-OARC uses `dnscap` for DITL data collections.\n\nSome of its features include:\n- Understands both IPv4 and IPv6\n- Captures UDP, TCP, and IP fragments.\n- Collect only queries, responses, or both (`-s` option)\n- Collect for only certain source/destination addresses (`-a` `-z` `-A` `-Z` options)\n- Periodically creates new pcap files (`-t` option)\n- Spawns an upload script after closing a pcap file (`-k` option)\n- Will start and stop collecting at specific times (`-B` `-E` options)\n\nMore information may be found here:\n- https://www.dns-oarc.net/tools/dnscap\n- https://www.dns-oarc.net/oarc/data/ditl\n\nIssues should be reported here:\n- https://github.com/DNS-OARC/dnscap/issues\n\nGeneral support and discussion:\n- Mattermost: https://chat.dns-oarc.net/community/channels/oarc-software\n\n## Dependencies\n\n`dnscap` requires a couple of libraries beside a normal C compiling\nenvironment with autoconf, automake, libtool and pkgconfig.\n\n`dnscap` has a non-optional dependency on the PCAP library and LDNS.\n\nTo install the dependencies under Debian/Ubuntu:\n```\napt-get install -y libpcap-dev libldns-dev zlib1g-dev libyaml-perl libssl-dev\n```\n\nTo install the dependencies under CentOS (with EPEL/PowerTools enabled):\n```\nyum install -y libpcap-devel ldns-devel openssl-devel zlib-devel perl-YAML\n```\n\nFor the following OS you will need to install some of the dependencies\nfrom source or Ports, these instructions are not included.\n\nTo install some of the dependencies under FreeBSD 10+ using `pkg`:\n```\npkg install -y libpcap ldns p5-YAML openssl-devel\n```\n\nTo install some of the dependencies under OpenBSD 5+ using `pkg_add`:\n```\npkg_add libldns p5-YAML\n```\n\nNOTE: It is recommended to install the PCAP library from source/ports on\nOpenBSD since the bundled version is an older and modified version.\n\n### Dependencies for `cryptopant.so` plugin\n\nFor this plugin a library call `cryptopANT` is required and the original\ncan be found here: https://ant.isi.edu/software/cryptopANT/index.html .\n\nFor DNS-OARC packages we build our own fork, with slight modifications to\nconform across distributions, of this library which is included in the same\npackage repository as `dnscap`. The modifications and packaging files can be\nfound here: https://github.com/DNS-OARC/cryptopANT .\n\n## Building from source tarball\n\nThe [source tarball from DNS-OARC](https://www.dns-oarc.net/tools/dnscap)\ncomes prepared with `configure`:\n\n```\ntar zxvf dnscap-version.tar.gz\ncd dnscap-version\n./configure [options]\nmake\nmake install\n```\n\n## Building from Git repository\n\nIf you are building `dnscap` from it's Git repository you will first need\nto initiate the Git submodules that exists and later create autoconf/automake\nfiles, this will require a build environment with autoconf, automake, libtool\nand pkg-config to be installed.\n\n```\ngit clone https://github.com/DNS-OARC/dnscap.git\ncd dnscap\ngit submodule update --init\n./autogen.sh\n./configure [options]\nmake\nmake install\n```\n\n### 64-bit libraries\n\nIf you need to link against 64-bit libraries found in non-standard\nlocations, provide the location by setting LDFLAGS before running\nconfigure:\n\n```\n$ env LDFLAGS=-L/usr/lib64 ./configure\n```\n\n### OpenBSD\n\nFor OpenBSD you probably installed libpcap in `/usr/local` so you will need\nto tell `configure` where to find the libraries and header files:\n\n```\n$ env CFLAGS=\"-I/usr/local/include\" LDFLAGS=\"-L/usr/local/lib\" ./configure\n```\n\n## Plugins\n\n`dnscap` comes bundled with a set of plugins, see `-P` option.\n\n- `anonaes128.so`: Anonymize IP addresses using AES128\n- `anonmask.so`: Pseudo-anonymize IP addresses by masking them\n- `asudp.so`: Rewrites outgoing packet, takes the DNS and constructs UDP packets, can be used together with layers and reassembling/defrag'ing packets\n- `cryptopan.so`: Anonymize IP addresses using an extension to Crypto-PAn (College of Computing, Georgia Tech) made by David Stott (Lucent)\n- `cryptopant.so`: Anonymize IP addresses using cryptopANT, a different implementation of Crypto-PAn made by the ANT project at USC/ISI\n- `ipcrypt.so`: Anonymize IP addresses using ipcrypt create by Jean-Philippe Aumasson\n- `pcapdump.so`: Dump DNS into a PCAP with some filtering options\n- `royparse.so`: Splits a PCAP into two streams; queries in PCAP format and responses in ASCII format\n- `rssm.so`: Root Server Scaling Measurement plugin, see it's [README.md](plugins/rssm/README.md) for more information\n- `rzkeychange.so`: RFC8145 key tag signal collection and reporting plugin\n- `txtout.so`: Dump DNS as one-line text\n- `eventlog.so`: Syslog style output for easy parsing, use with a SIEM, etc.\n\nThere is also a `template` plugin in the source repository to help others\ndevelop new plugins.\n\n## CBOR DNS Stream Format\n\nThis is an experimental format for representing DNS information in CBOR\nwith the goals to:\n- Be able to stream the information\n- Support incomplete, broken and/or invalid DNS\n- Have close to no data quality and signature degradation\n- Support additional non-DNS meta data (such as ICMP/TCP attributes)\n\nRead [CBOR_DNS_STREAM.md](https://github.com/DNS-OARC/dnscap/blob/develop/CBOR_DNS_STREAM.md) for more information.\n\nTo enable this output please follow the instructions below for Enabling\nCBOR Output, note that this only requires Tinycbor.\n\n### Outputting to CBOR DNS Stream (CDS)\n\nTo output to the CDS format you tell `dnscap` to write to a file and set\nthe format to CDS.  CDS is a stream of CBOR objects and you can control how\nmany objects are kept in memory until flushed to the file by setting\n`cds_cbor_size`, note that this is bytes of memory and not number of objects.\nWhen it reaches this limit it will write the output and start on a new file.\nRead `dnscap`'s man page for all CDS extended options.\n\n```\nsrc/dnscap [...] -w \u003cfile\u003e -F cds [ -o cds_cbor_size=\u003cbytes\u003e ]\n```\n\n## CBOR\n\nThere is experimental support for CBOR output using LDNS and Tinycbor with\na data structure described in the DNS-in-JSON draft.\n\nhttps://datatracker.ietf.org/doc/draft-hoffman-dns-in-json/\n\n### Enabling CBOR Output\n\nTo enable the CBOR output support you will need to install it's dependencies\nbefore running `configure`, LDNS exists for most distributions but Tinycbor\nis new so you need to download and compile it, you do not necessary need to\ninstall it as shown in the example below.\n\n```sh\ngit clone https://github.com/DNS-OARC/dnscap.git\ncd dnscap\ngit submodule update --init\ngit clone https://github.com/01org/tinycbor.git\ncd tinycbor\ngit checkout v0.4.2\nmake\ncd ..\nsh autogen.sh\nCFLAGS=\"-I$PWD/tinycbor/src\" LDFLAGS=\"-L$PWD/tinycbor/lib\" LIBS=\"-ltinycbor\" ./configure\nmake\n```\n\n**NOTE**: Paths in `CFLAGS` and `LDFLAGS` must be absolute.\n\n### CBOR to JSON\n\nTinycbor comes with a tool to convert CBOR to JSON, check `bin/cbordump -h`\nin the Tinycbor directory after having compiled it.\n\n### Outputting to CBOR\n\nTo output to the CBOR format you tell `dnscap` to write to a file and set\nthe format to CBOR.  Since Tinycbor constructs everything in memory there\nis a limit and when it is reached it will write the output and start on a\nnew file.  You can control the number of bytes with the extended option\n`cbor_chunk_size`.\n\n```\nsrc/dnscap [...] -w \u003cfile\u003e -F cbor [ -o cbor_chunk_size=\u003cbytes\u003e ]\n```\n\n### Additional attributes\n\nThere is currently an additional attribute added to the CBOR object which\ncontains the IP information as following:\n\n```\n\"ip\": [\n  \u003cproto\u003e,\n  \"\u003csource ip address\u003e\",\n  \u003csource port\u003e\n  \"\u003cdestination ip address\u003e\",\n  \u003cdestination port\u003e\n]\n```\n\nExample:\n\n```json\n\"ip\": [\n  17,\n  \"127.0.0.1\",\n  34856,\n  \"127.0.0.1\",\n  53\n]\n```\n\n### Limitations, deviations and issues\n\nSince this is still experimental there are of course some issues:\n- RDATA is in binary format\n- DNS packet are parsed by LDNS which can fail if malformed packets\n- `dateSeconds` is added as a C `double` which might loose some of the time precision\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDNS-OARC%2Fdnscap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDNS-OARC%2Fdnscap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDNS-OARC%2Fdnscap/lists"}