{"id":14021758,"url":"https://github.com/bytedance/netcap","last_synced_at":"2025-05-15T10:00:38.023Z","repository":{"id":244074339,"uuid":"808709942","full_name":"bytedance/netcap","owner":"bytedance","description":null,"archived":false,"fork":false,"pushed_at":"2025-01-10T02:41:18.000Z","size":179,"stargazers_count":677,"open_issues_count":7,"forks_count":84,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-04-14T16:53:39.578Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/bytedance.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","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}},"created_at":"2024-05-31T16:42:00.000Z","updated_at":"2025-04-13T08:50:32.000Z","dependencies_parsed_at":"2024-06-12T20:18:12.613Z","dependency_job_id":"fecb6b56-2cc3-466e-a615-14c8abbc571f","html_url":"https://github.com/bytedance/netcap","commit_stats":{"total_commits":5,"total_committers":5,"mean_commits":1.0,"dds":0.8,"last_synced_commit":"624dbd204ca7d083608c61cced60834fd5f1cf22"},"previous_names":["bytedance/netcap"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytedance%2Fnetcap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytedance%2Fnetcap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytedance%2Fnetcap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytedance%2Fnetcap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bytedance","download_url":"https://codeload.github.com/bytedance/netcap/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254319715,"owners_count":22051072,"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-08-11T14:01:01.155Z","updated_at":"2025-05-15T10:00:36.356Z","avatar_url":"https://github.com/bytedance.png","language":"Go","funding_links":[],"categories":["Go","抓包工具","Tool"],"sub_categories":["TUI Tool"],"readme":"# netcap\n\n## 简介\n\nnetcap(内部称为xcap)是一个基于bcc，可对含skb作为参数的系统函数，或者基于DPDK的mbuf抓包分析的工具。简单试用如下：\n\n```shell\nnetcap skb -f icmp_rcv@1 -e \"host 10.227.0.72\" -i eth0\n```\n\n## 安装依赖\n\nnetcap工具依赖安装`bcc`包。\n\n\n## 命令行参数说明\n\n可以通过netcap的help获取用法资料以及example如下:\n\n```shell\n# 查看 skb 模式支持的参数\nnetcap help skb\n# 查看 mbuf 模式支持的参数\nnetcap help mbuf\n```\n\n本质上，命令行参数分为以下3类:\n\n* skb模式与mbuf模式通用的\n* 仅skb模式的\n* 仅mbuf/raw模式的\n\n### 通用命令行参数\n\n* -f  function_name\u003c@param1\u003e\u003c@param2\u003e\n\n  设置需要trace的函数格式, function_name表示要trace的函数名称，并可支持多点抓包，用逗号分隔，例如 `ip_local_deliver@1,icmp_rcv@1`。\n\n  对于skb模式，支持:\n\n  * -f tracepoint:net:netif_receive_skb  是tracepoint的方式，此时无需param1和param2。\n  * -f icmp_rcv@1  是kprbe的方式，需要param1，表示skb是被trace函数的第几个参数（从1开始），无需param2。\n  * -f tcp_rcv_established@2@1 这里@2表示第2个参数是skb，后面的@1是ext扩展参数,关于此参数详见 --ext-action 描述。\n\n  对于mbuf模式, 由于DPDK会使用mbuf数组，故使用param2的时候表示是mbuf数组，仅仅使用param1的时候是mbuf：\n\n  * -f usdt:rx_one@1  是usdt的方式的，并且rx_one的usdt第一个参数param1是mbuf指针。\n  * -f usdt:rx_array@1@2  是usdt的方式的，并且rx_array的usdt第一个参数param1是mbuf指针的数组，第二个参数param2是前面说的数组的大小。\n  * -f func@1  是uprobe的trace,此处表示mbuf。\n  * -f func_array@1@2  是uprobe的trace，此处表示mbuf数组。\n\n  Note: -f 参数较为复杂，可以结合后面的Example理解。\n\n* -e  expression\n\n  设置需要过滤数据包的表达式，此表达式基于tcpdump的语法。\n\n* -t  tcpdump-flags\n\n  设置tcpdump的flags, 例如想以 -nnve 的tcpdump方式查看数据包，即可输入 -t \"-nnve\"。\n\n* -w  file\n\n  --write-file-rotate  rotate-num \n\n  抓包写文件，同tcpdump，通过 --write-file-rotate 指定的 rotate-num  表示循环抓包，即抓最后的rotate-num个包，写入pcap文件。\n\n* -c  capture-count\n\n  抓多少个包后退出，设置为0或不设置表示不限制次数，同tcpdump。\n\n* --capture-max-size  max\n\n  这个size是指抓的包，保存到buff的大小，如果包长超过这个值，则包会被截断。\n\n* --gather\n\n  汇总输出用法，此参数为开关参数，打开此开关忽略 -w 参数。\n\n  gather功能仅在多点trace下使用，并以第一个被trace的点为基准值，跟踪数据包到达后续trace点的延迟信息。\n\n  gather功能它持有的子参数如下：\n\n  * --gather-buffer-size  size : 设置buff的大小。\n  * --gather-timeout  timeout : 超时时间。\n  * --gather-distinguish-by-pointer : 以指针(skb或mbuf)来标识同一个数据包，否则以包内容。\n  * --gather-output-color : 设置打印gather的颜色: red|green|yellow|blue|purple|cyan。\n\n  此功能较为复杂，可参照Example理解。\n\n* --ext-filter  filename.c\n\n  用户自定义filter，[只看TCP的FIN包的自定义filter例子](doc/example/ext_filter/skb_filter_tcp_fin.c)\n  ```shell\n  netcap skb -f tcp_drop@2 -e 'port 8888' -t \"-nnv\"  --ext-filter skb_filter_tcp_fin.c\n  ```\n\n* --ext-action  filename.c\n\n  用户自定义的匹配后的action，在action中netcap会把user填充的自定义的结构体的信息与pkt一起输出到控制台。[输出sock信息的例子](doc/example/ext_action/sk_stat_action.c)\n  ```shell\n  # 其中 tcp_rcv_established @2表示第2个参数为skb, @1表示第1个参数sk作为ext传入到 --ext-action指定的函数\n  netcap skb -f tcp_rcv_established@2@1 -e \"port 8888\"  --ext-action sk_stat_action.c\n  ```\n  输出如下图所示：\n  ![](doc/jpg/ext-action.jpg)\n  * --ext-output-color : 设置打印user Ouput的颜色: red|green|yellow|blue|purple|cyan。\n\n* --dry-run\n\n  并不真正执行,只是打印出生成的ebpf代码。\n\n### skb模式的参数\n\n* -i  interface\n\n  例如 -i eth0, 同tcpdump\n\n* --fake-hdr\n\n  在某些TX方向函数(例如 __ip_finish_output)，内核还没有给它填充eth,ip等头信息,使用此选项可以由netcap根据skb的sock信息伪造出header来适配tcpdump过滤语法。\n  \n* --skb-data\n\n  不设置此参数表示使用 netcap 的默认策略来寻找packet开始地址，若设置此标志，则使用 skb-\u003edata + offset 作为数据包的开始。其中的offset由 --skb-data-offset 设置。需要设置此参数的场景：某些特殊的函数行为，导致默认策略找到的地址错误。\n  \n* -S\n\n  开关参数，设置后，伴随pcap打印此包对应的kstack，并忽略 --gather 和 -w 参数。\n  \n  * --stack-dump-color : 设置打印kstack的颜色: red|green|yellow|blue|purple|cyan。\n\n### mbuf/raw模式的参数\n  注：mbuf用于DPDK开发，raw用于AFXDP开发。\n  注：usdt受限于上游库修改，用兴趣的可以自行魔改。\n\n* -p  pid\n\n  设置要trace的DPDK程序的pid。\n\n## Examle\n\n### skb的常规用法\n\n```shell\n# 在icmp_rcv抓包，并指定eth0为收包网卡，并按tcpdump语法过滤\nnetcap skb -f icmp_rcv@1 -e \"host 10.227.0.72\" -i eth0 -t \"-nnv\"\n\n# 把抓到的包写入文件icmp.pcap\nnetcap skb -f icmp_rcv@1 -e \"host 10.227.0.72\" -i eth0 -w icmp.pcap\n\n# 打印kstack\nnetcap skb -f icmp_rcv@1 -e \"host 10.227.0.72\" -i eth0 -S\n\n# 在tracepoint抓包，注意:tracepoint不需要使用@传递skb是第几个参数\nnetcap skb -f tracepoint:net:netif_receive_skb@1 -i eth0 -e \"host 10.227.0.72\"\n```\n\n### mbuf的常规用法\n\n```shell\n# 在pid为1111的DPDK进程中，对于you_func函数(uprobe)抓包，其中mbuf指针作为此函数的第一个参数\nnetcap mbuf -f you_func@1 -e \"tcp and port 80\" -t \"-nnve\" --pid 1111\n\n# 在pid为1111的DPDK进程中，对于对于you_func函数函数(uprobe)抓包，其中vec_func传递的是mbuf指针数组,故需2个参数\nnetcap mbuf -f vec_func@1@2 -e \"tcp and port 80\" -t \"-nnve\" --pid 1111\n\n# 在多个函数同时抓包\nnetcap mbuf -f func_rcv@1,func_send@1 -e \"tcp\" --pid 111\n```\n\n### gather用法\n\ngather只能针对trace多个函数（即 -f 后面要用多个函数），并把第一个作为基准。举例如下：\n\n```shell\n# 使用gather统计以下函数，并用cyan的颜色输出信息\nnetcap skb -f tracepoint:net:netif_receive_skb,ip_local_deliver@1,ip_local_deliver_finish@3,icmp_rcv@1 -e \"host 10.227.0.72 and icmp\" -i eth0  --gather --gather-output-color cyan \n```\n\n![](doc/jpg/x_gather.jpeg)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytedance%2Fnetcap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbytedance%2Fnetcap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytedance%2Fnetcap/lists"}