{"id":20858826,"url":"https://github.com/controlplaneio/netassertv2-packet-sniffer","last_synced_at":"2025-05-12T08:31:52.411Z","repository":{"id":168963619,"uuid":"598692214","full_name":"controlplaneio/netassertv2-packet-sniffer","owner":"controlplaneio","description":"This repo houses Netassertv2 TCP/UDP Packet sniffer","archived":false,"fork":false,"pushed_at":"2024-08-19T07:43:14.000Z","size":80,"stargazers_count":4,"open_issues_count":2,"forks_count":2,"subscribers_count":15,"default_branch":"main","last_synced_at":"2024-08-19T08:58:10.419Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/controlplaneio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-07T16:14:03.000Z","updated_at":"2024-08-16T07:40:28.000Z","dependencies_parsed_at":"2024-08-19T08:52:39.259Z","dependency_job_id":"b7820fa2-0fc3-48fd-bfc0-e9ca7cd1141a","html_url":"https://github.com/controlplaneio/netassertv2-packet-sniffer","commit_stats":null,"previous_names":["controlplaneio/netassertv2-packet-sniffer"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/controlplaneio%2Fnetassertv2-packet-sniffer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/controlplaneio%2Fnetassertv2-packet-sniffer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/controlplaneio%2Fnetassertv2-packet-sniffer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/controlplaneio%2Fnetassertv2-packet-sniffer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/controlplaneio","download_url":"https://codeload.github.com/controlplaneio/netassertv2-packet-sniffer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225130752,"owners_count":17425506,"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":[],"created_at":"2024-11-18T04:47:40.750Z","updated_at":"2024-11-18T04:47:41.538Z","avatar_url":"https://github.com/controlplaneio.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Netassertv2-Packet-Sniffer\n\n[![Testing Workflow][testing_workflow_badge]][testing_workflow_badge]\n[![Release Workflow][release_workflow_badge]][release_workflow_badge]\n\nThe `Netassertv2-Packet-Sniffer` is a Go program designed to sniff layer 4 (TCP or UDP) traffic and identify specific strings within it. It accepts the following environment variables:\n\n| Environment Variable | Go Type | Default Value | Purpose |\n| --- | --- | --- | --- |\n| IFACE | string | eth0 | The network interface to listen on |\n| SNAPLEN | int | 1024 | The packet snap length |\n| PROMISC | bool | false | Should the network interface be set to Promiscuous mode |\n| SEARCH_STRING | string | control-plane.io | The string to search in the TCP/UDP packet |\n| PROTOCOL | string | tcp | The protocol we are interested in, can be tcp or udp |\n| MATCHES | int | 3 | The number of matches after which the program will exit with a status code of 0 |\n| TIMEOUT_SECONDS | int | 60 | The total duration during which we will capture the traffic. If we do not get enough matches (defined by `$MATCHES`) during this time, we exit with a status code of 1 |\n\nIf the specified number of matches are found within the defined timeout period, the program will exit with a status code of 0. If the required matches are not found within the given time, the program will exit with a status code of 1.\nThe program does not need to run with root privileges(uid:gid 0:0) but it requires the `CAP_NET_RAW` capability. It is allowed by default by many container runtimes so no action should be needed, otherwise it can be explicitly set using `--cap-add NET_RAW` (Docker example). The Sniffer binary has already associated the aforementioned capability in the Docker image\n\n```bash\nsetcap cap_net_raw+ep /usr/bin/packet-capture\n```\n\nYou can pull the latest Docker image from `docker.io/controlplane/netassertv2-packet-sniffer:latest`\n\n## Libpcap Prerequisite\n\n- This program uses the [Go Packet](https://github.com/google/gopacket) library for packet processing and uses C Bindings for libpcap. Therefore, you need to install libpacp dependencies for your OS to compile the program.\n\n```bash\nFor Fedora/RHEL/CentOS\n$ sudo dnf install libpcap-devel\nFor Debian/Ubuntu\n$ sudo apt update \u0026\u0026 sudo apt install libpcap-dev -y\n\n```\n\n## Local testing\n\nYou can build and test the binary with the help of `netcat` server. To test the `TCP` protocol, run the following commands on different terminals:\n\nIn the first terminal run the packet sniffer, you will need to enter sudo password:\n\n```bash\n❯ make run-tcp\nsudo bin/packet-capture -protocol=tcp -interface=lo -matches 3\n2023-03-06T17:01:35.198Z\tinfo\tnetassertv2-packet-sniffer/main.go:70\tWorking with following configuration:\n{NetworkInterface:lo SnapLen:1024 Promisc:false SearchString:control-plane.io Protocol:tcp Environment:production NumberOfMatches:3 TimeoutSeconds:60}\n\t{\"service\": \"packet-capture\", \"version\": \"development\"}\n2023-03-06T17:01:35.236Z\tinfo\tnetassertv2-packet-sniffer/main.go:98\tcapturing \"tcp\" traffic on \"lo\" interface\t{\"service\": \"packet-capture\", \"version\": \"development\"}\n2023-03-06T17:01:35.236Z\tinfo\tnetassertv2-packet-sniffer/main.go:101\tstarting to process packets\t{\"service\": \"packet-capture\", \"version\": \"development\"}\n...\n....\n```\n\nThis will launch the packet sniffer which will capture TCP traffic on local loopback adapater and search for string `control-plane.io` in the captured TCP packets.\n\nIn the second terminal run a `netcat` server the listens on port 12345:\n```bash\n\n❯ make run-netcat-tcp-server\nwhile true; do nc -vl localhost 12345; done\nListening on view-localhost 12345\n\n```\n\nIn the third terminal run a `netcat` client that will connect to the server on `localhost:12345` and send packet with payload `control-plane.io`\n\n```bash\n\n❯ make run-netcat-tcp-client\nfor i in `seq 1 4`; do echo 'control-plane.io' | nc -q 1 -v localhost 12345; done\nConnection to localhost (127.0.0.1) 12345 port [tcp/*] succeeded!\nConnection to localhost (127.0.0.1) 12345 port [tcp/*] succeeded!\nConnection to localhost (127.0.0.1) 12345 port [tcp/*] succeeded!\nConnection to localhost (127.0.0.1) 12345 port [tcp/*] succeeded!\n\n```\n\nThe sniffer on the first terminal should exit with the following message:\n\n```bash\n2023-03-06T17:04:18.654Z\tinfo\tnetassertv2-packet-sniffer/main.go:140\tnumber of matches reached{\"service\": \"packet-capture\", \"version\": \"development\"}\n```\n\n[testing_workflow_badge]: https://github.com/controlplaneio/netassertv2-packet-sniffer/workflows/Lint%20and%20Build/badge.svg\n[release_workflow_badge]: https://github.com/controlplaneio/netassertv2-packet-sniffer/workflows/Docker%20build%20and%20publish/badge.svg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontrolplaneio%2Fnetassertv2-packet-sniffer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcontrolplaneio%2Fnetassertv2-packet-sniffer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontrolplaneio%2Fnetassertv2-packet-sniffer/lists"}