xref: /aosp_15_r20/external/bcc/tools/execsnoop_example.txt (revision 387f9dfdfa2baef462e92476d413c7bc2470293e)
1*387f9dfdSAndroid Build Coastguard WorkerDemonstrations of execsnoop, the Linux eBPF/bcc version.
2*387f9dfdSAndroid Build Coastguard Worker
3*387f9dfdSAndroid Build Coastguard Worker
4*387f9dfdSAndroid Build Coastguard Workerexecsnoop traces new processes. For example, tracing the commands invoked when
5*387f9dfdSAndroid Build Coastguard Workerrunning "man ls":
6*387f9dfdSAndroid Build Coastguard Worker
7*387f9dfdSAndroid Build Coastguard Worker# ./execsnoop
8*387f9dfdSAndroid Build Coastguard WorkerPCOMM            PID    RET ARGS
9*387f9dfdSAndroid Build Coastguard Workerbash             15887    0 /usr/bin/man ls
10*387f9dfdSAndroid Build Coastguard Workerpreconv          15894    0 /usr/bin/preconv -e UTF-8
11*387f9dfdSAndroid Build Coastguard Workerman              15896    0 /usr/bin/tbl
12*387f9dfdSAndroid Build Coastguard Workerman              15897    0 /usr/bin/nroff -mandoc -rLL=169n -rLT=169n -Tutf8
13*387f9dfdSAndroid Build Coastguard Workerman              15898    0 /usr/bin/pager -s
14*387f9dfdSAndroid Build Coastguard Workernroff            15900    0 /usr/bin/locale charmap
15*387f9dfdSAndroid Build Coastguard Workernroff            15901    0 /usr/bin/groff -mtty-char -Tutf8 -mandoc -rLL=169n -rLT=169n
16*387f9dfdSAndroid Build Coastguard Workergroff            15902    0 /usr/bin/troff -mtty-char -mandoc -rLL=169n -rLT=169n -Tutf8
17*387f9dfdSAndroid Build Coastguard Workergroff            15903    0 /usr/bin/grotty
18*387f9dfdSAndroid Build Coastguard Worker
19*387f9dfdSAndroid Build Coastguard WorkerThe output shows the parent process/command name (PCOMM), the PID, the return
20*387f9dfdSAndroid Build Coastguard Workervalue of the exec() (RET), and the filename with arguments (ARGS).
21*387f9dfdSAndroid Build Coastguard Worker
22*387f9dfdSAndroid Build Coastguard WorkerThis works by traces the execve() system call (commonly used exec() variant),
23*387f9dfdSAndroid Build Coastguard Workerand shows details of the arguments and return value. This catches new processes
24*387f9dfdSAndroid Build Coastguard Workerthat follow the fork->exec sequence, as well as processes that re-exec()
25*387f9dfdSAndroid Build Coastguard Workerthemselves. Some applications fork() but do not exec(), eg, for worker
26*387f9dfdSAndroid Build Coastguard Workerprocesses, which won't be included in the execsnoop output.
27*387f9dfdSAndroid Build Coastguard Worker
28*387f9dfdSAndroid Build Coastguard Worker
29*387f9dfdSAndroid Build Coastguard WorkerThe -x option can be used to include failed exec()s. For example:
30*387f9dfdSAndroid Build Coastguard Worker
31*387f9dfdSAndroid Build Coastguard Worker# ./execsnoop -x
32*387f9dfdSAndroid Build Coastguard WorkerPCOMM            PID    RET ARGS
33*387f9dfdSAndroid Build Coastguard Workersupervise        9660     0 ./run
34*387f9dfdSAndroid Build Coastguard Workersupervise        9661     0 ./run
35*387f9dfdSAndroid Build Coastguard Workermkdir            9662     0 /bin/mkdir -p ./main
36*387f9dfdSAndroid Build Coastguard Workerrun              9663     0 ./run
37*387f9dfdSAndroid Build Coastguard Workerchown            9664     0 /bin/chown nobody:nobody ./main
38*387f9dfdSAndroid Build Coastguard Workerrun              9665     0 /bin/mkdir -p ./main
39*387f9dfdSAndroid Build Coastguard Workersupervise        9667     0 ./run
40*387f9dfdSAndroid Build Coastguard Workerrun              9660    -2 /usr/local/bin/setuidgid nobody /command/multilog t ./main
41*387f9dfdSAndroid Build Coastguard Workerchown            9668     0 /bin/chown nobody:nobody ./main
42*387f9dfdSAndroid Build Coastguard Workerrun              9666     0 /bin/chmod 0777 main
43*387f9dfdSAndroid Build Coastguard Workerrun              9663    -2 /usr/local/bin/setuidgid nobody /command/multilog t ./main
44*387f9dfdSAndroid Build Coastguard Workerrun              9669     0 /bin/mkdir -p ./main
45*387f9dfdSAndroid Build Coastguard Workerrun              9661    -2 /usr/local/bin/setuidgid nobody /command/multilog t ./main
46*387f9dfdSAndroid Build Coastguard Workersupervise        9670     0 ./run
47*387f9dfdSAndroid Build Coastguard Worker[...]
48*387f9dfdSAndroid Build Coastguard Worker
49*387f9dfdSAndroid Build Coastguard WorkerThis example shows various regular system daemon activity, including some
50*387f9dfdSAndroid Build Coastguard Workerfailures (trying to execute a /usr/local/bin/setuidgid, which I just noticed
51*387f9dfdSAndroid Build Coastguard Workerdoesn't exist).
52*387f9dfdSAndroid Build Coastguard Worker
53*387f9dfdSAndroid Build Coastguard Worker
54*387f9dfdSAndroid Build Coastguard WorkerA -T option can be used to include a time column, a -t option to include a
55*387f9dfdSAndroid Build Coastguard Workertimestamp column, and a -n option to match on a name. Regular expressions
56*387f9dfdSAndroid Build Coastguard Workerare allowed.
57*387f9dfdSAndroid Build Coastguard WorkerFor example, matching commands containing "mount":
58*387f9dfdSAndroid Build Coastguard Worker
59*387f9dfdSAndroid Build Coastguard Worker# ./execsnoop -Ttn mount
60*387f9dfdSAndroid Build Coastguard WorkerTIME     TIME(s) PCOMM            PID    PPID  RET ARGS
61*387f9dfdSAndroid Build Coastguard Worker14:08:23 2.849   mount            18049  1045    0 /bin/mount -p
62*387f9dfdSAndroid Build Coastguard Worker
63*387f9dfdSAndroid Build Coastguard WorkerThe -l option can be used to only show command where one of the arguments
64*387f9dfdSAndroid Build Coastguard Workermatches specified line. The limitation is that we are looking only into first 20
65*387f9dfdSAndroid Build Coastguard Workerarguments of the command. For example, matching all command where one of the argument
66*387f9dfdSAndroid Build Coastguard Workeris "testpkg":
67*387f9dfdSAndroid Build Coastguard Worker
68*387f9dfdSAndroid Build Coastguard Worker# ./execsnoop.py -l testpkg
69*387f9dfdSAndroid Build Coastguard WorkerPCOMM            PID    PPID   RET ARGS
70*387f9dfdSAndroid Build Coastguard Workerservice          3344535 4146419   0 /usr/sbin/service testpkg status
71*387f9dfdSAndroid Build Coastguard Workersystemctl        3344535 4146419   0 /bin/systemctl status testpkg.service
72*387f9dfdSAndroid Build Coastguard Workeryum              3344856 4146419   0 /usr/local/bin/yum remove testpkg
73*387f9dfdSAndroid Build Coastguard Workerpython           3344856 4146419   0 /usr/local/bin/python /usr/local/bin/yum remove testpkg
74*387f9dfdSAndroid Build Coastguard Workeryum              3344856 4146419   0 /usr/bin/yum remove testpkg
75*387f9dfdSAndroid Build Coastguard Workeryum              3345086 4146419   0 /usr/local/bin/yum install testpkg
76*387f9dfdSAndroid Build Coastguard Workerpython           3345086 4146419   0 /usr/local/bin/python /usr/local/bin/yum install testpkg
77*387f9dfdSAndroid Build Coastguard Workeryum              3345086 4146419   0 /usr/bin/yum install testpkg
78*387f9dfdSAndroid Build Coastguard Workerrpm              3345452 4146419   0 /bin/rpm -qa testpkg
79*387f9dfdSAndroid Build Coastguard Worker
80*387f9dfdSAndroid Build Coastguard Worker
81*387f9dfdSAndroid Build Coastguard WorkerThe --cgroupmap option filters based on a cgroup set. It is meant to be used
82*387f9dfdSAndroid Build Coastguard Workerwith an externally created map.
83*387f9dfdSAndroid Build Coastguard Worker
84*387f9dfdSAndroid Build Coastguard Worker# ./execsnoop --cgroupmap /sys/fs/bpf/test01
85*387f9dfdSAndroid Build Coastguard Worker
86*387f9dfdSAndroid Build Coastguard WorkerFor more details, see docs/special_filtering.md
87*387f9dfdSAndroid Build Coastguard Worker
88*387f9dfdSAndroid Build Coastguard WorkerThe -U option include UID on output:
89*387f9dfdSAndroid Build Coastguard Worker
90*387f9dfdSAndroid Build Coastguard Worker# ./execsnoop -U
91*387f9dfdSAndroid Build Coastguard Worker
92*387f9dfdSAndroid Build Coastguard WorkerUID   PCOMM            PID    PPID   RET ARGS
93*387f9dfdSAndroid Build Coastguard Worker1000  ls               171318 133702   0 /bin/ls --color=auto
94*387f9dfdSAndroid Build Coastguard Worker1000  w                171322 133702   0 /usr/bin/w
95*387f9dfdSAndroid Build Coastguard Worker
96*387f9dfdSAndroid Build Coastguard WorkerThe -u options filters output based process UID. You also can use username as
97*387f9dfdSAndroid Build Coastguard Workerargument, in that cause UID will be looked up using getpwnam (see man 3 getpwnam).
98*387f9dfdSAndroid Build Coastguard Worker
99*387f9dfdSAndroid Build Coastguard Worker# ./execsnoop -Uu 1000
100*387f9dfdSAndroid Build Coastguard WorkerUID   PCOMM            PID    PPID   RET ARGS
101*387f9dfdSAndroid Build Coastguard Worker1000  ls               171335 133702   0 /bin/ls --color=auto
102*387f9dfdSAndroid Build Coastguard Worker1000  man              171340 133702   0 /usr/bin/man getpwnam
103*387f9dfdSAndroid Build Coastguard Worker1000  bzip2            171341 171340   0 /bin/bzip2 -dc
104*387f9dfdSAndroid Build Coastguard Worker1000  bzip2            171342 171340   0 /bin/bzip2 -dc
105*387f9dfdSAndroid Build Coastguard Worker1000  bzip2            171345 171340   0 /bin/bzip2 -dc
106*387f9dfdSAndroid Build Coastguard Worker1000  manpager         171355 171340   0 /usr/bin/manpager
107*387f9dfdSAndroid Build Coastguard Worker1000  less             171355 171340   0 /usr/bin/less
108*387f9dfdSAndroid Build Coastguard Worker
109*387f9dfdSAndroid Build Coastguard WorkerUSAGE message:
110*387f9dfdSAndroid Build Coastguard Worker
111*387f9dfdSAndroid Build Coastguard Worker# ./execsnoop -h
112*387f9dfdSAndroid Build Coastguard Workerusage: execsnoop.py [-h] [-T] [-t] [-x] [--cgroupmap CGROUPMAP]
113*387f9dfdSAndroid Build Coastguard Worker                    [--mntnsmap MNTNSMAP] [-u USER] [-q] [-n NAME] [-l LINE]
114*387f9dfdSAndroid Build Coastguard Worker                    [-U] [--max-args MAX_ARGS] [-P PPID]
115*387f9dfdSAndroid Build Coastguard Worker
116*387f9dfdSAndroid Build Coastguard WorkerTrace exec() syscalls
117*387f9dfdSAndroid Build Coastguard Worker
118*387f9dfdSAndroid Build Coastguard Workeroptional arguments:
119*387f9dfdSAndroid Build Coastguard Worker  -h, --help            show this help message and exit
120*387f9dfdSAndroid Build Coastguard Worker  -T, --time            include time column on output (HH:MM:SS)
121*387f9dfdSAndroid Build Coastguard Worker  -t, --timestamp       include timestamp on output
122*387f9dfdSAndroid Build Coastguard Worker  -x, --fails           include failed exec()s
123*387f9dfdSAndroid Build Coastguard Worker  --cgroupmap CGROUPMAP
124*387f9dfdSAndroid Build Coastguard Worker                        trace cgroups in this BPF map only
125*387f9dfdSAndroid Build Coastguard Worker  --mntnsmap MNTNSMAP   trace mount namespaces in this BPF map only
126*387f9dfdSAndroid Build Coastguard Worker  -u USER, --uid USER   trace this UID only
127*387f9dfdSAndroid Build Coastguard Worker  -q, --quote           Add quotemarks (") around arguments.
128*387f9dfdSAndroid Build Coastguard Worker  -n NAME, --name NAME  only print commands matching this name (regex), any
129*387f9dfdSAndroid Build Coastguard Worker                        arg
130*387f9dfdSAndroid Build Coastguard Worker  -l LINE, --line LINE  only print commands where arg contains this line
131*387f9dfdSAndroid Build Coastguard Worker                        (regex)
132*387f9dfdSAndroid Build Coastguard Worker  -U, --print-uid       print UID column
133*387f9dfdSAndroid Build Coastguard Worker  --max-args MAX_ARGS   maximum number of arguments parsed and displayed,
134*387f9dfdSAndroid Build Coastguard Worker                        defaults to 20
135*387f9dfdSAndroid Build Coastguard Worker  -P PPID, --ppid PPID  trace this parent PID only
136*387f9dfdSAndroid Build Coastguard Worker
137*387f9dfdSAndroid Build Coastguard Workerexamples:
138*387f9dfdSAndroid Build Coastguard Worker    ./execsnoop                      # trace all exec() syscalls
139*387f9dfdSAndroid Build Coastguard Worker    ./execsnoop -x                   # include failed exec()s
140*387f9dfdSAndroid Build Coastguard Worker    ./execsnoop -T                   # include time (HH:MM:SS)
141*387f9dfdSAndroid Build Coastguard Worker    ./execsnoop -P 181               # only trace new processes whose parent PID is 181
142*387f9dfdSAndroid Build Coastguard Worker    ./execsnoop -U                   # include UID
143*387f9dfdSAndroid Build Coastguard Worker    ./execsnoop -u 1000              # only trace UID 1000
144*387f9dfdSAndroid Build Coastguard Worker    ./execsnoop -u user              # get user UID and trace only them
145*387f9dfdSAndroid Build Coastguard Worker    ./execsnoop -t                   # include timestamps
146*387f9dfdSAndroid Build Coastguard Worker    ./execsnoop -q                   # add "quotemarks" around arguments
147*387f9dfdSAndroid Build Coastguard Worker    ./execsnoop -n main              # only print command lines containing "main"
148*387f9dfdSAndroid Build Coastguard Worker    ./execsnoop -l tpkg              # only print command where arguments contains "tpkg"
149*387f9dfdSAndroid Build Coastguard Worker    ./execsnoop --cgroupmap mappath  # only trace cgroups in this BPF map
150*387f9dfdSAndroid Build Coastguard Worker    ./execsnoop --mntnsmap mappath   # only trace mount namespaces in the map
151