add capable tool

README.md

@@ -145,7 +145,8 @@ verify_cpu+0
 
 bpftrace contains various tools, which also serve as examples of programming in the bpftrace language.
 
-- tools/[bashreadline](tools/bashreadline.bt): Print entered bash commands system wide. [Examples](tools/bashreadline_example.txt).
+- tools/[bashreadline.bt](tools/bashreadline.bt): Print entered bash commands system wide. [Examples](tools/bashreadline_example.txt).
+- tools/[capable.bt](tools/capable.bt): Trace security capabilitiy checks. [Examples](tools/capable_example.txt).
 
 For more eBPF observability tools, see [bcc tools](https://github.com/iovisor/bcc#tools).
 

man/man8/capable.8

+.TH capable 8  "2018-09-08" "USER COMMANDS"
+.SH NAME
+capable.bt \- Trace security capability checks (cap_capable()).
+.SH SYNOPSIS
+.B capable.bt
+.SH DESCRIPTION
+This traces security capability checks in the kernel, and prints details for
+each call. This can be useful for general debugging, and also security
+enforcement: determining a white list of capabilities an application needs.
+
+Since this uses BPF, only the root user can use this tool.
+.SH REQUIREMENTS
+CONFIG_BPF, bpftrace.
+.SH EXAMPLES
+.TP
+Trace all capability checks system-wide:
+#
+.B capable
+.SH FIELDS
+.TP
+TIME(s)
+Time of capability check: HH:MM:SS.
+.TP
+UID
+User ID.
+.TP
+PID
+Process ID.
+.TP
+COMM
+Process name.
+CAP
+Capability number.
+NAME
+Capability name. See capabilities(7) for descriptions.
+.TP
+AUDIT
+Whether this was an audit event.
+.SH OVERHEAD
+This adds low-overhead instrumentation to capability checks, which are expected
+to be low frequency, however, that depends on the application. Test in a lab
+environment before use.
+.SH SOURCE
+This is from bpftrace.
+.IP
+https://github.com/iovisor/bpftrace
+.PP
+Also look in the bpftrace distribution for a companion _examples.txt file containing
+example usage, output, and commentary for this tool.
+
+This is a bpftrace version of the bcc tool of the same name. The bcc tool
+provides options to customize the output.
+.IP
+https://github.com/iovisor/bcc
+.SH OS
+Linux
+.SH STABILITY
+Unstable - in development.
+.SH AUTHOR
+Brendan Gregg
+.SH SEE ALSO
+capabilities(7)

tools/capable.bt

+/*
+ * capable	Trace security capabilitiy checks (cap_capable()).
+ *		For Linux, uses bpftrace and eBPF.
+ *
+ * USAGE: capable.bt
+ *
+ * This is a bpftrace version of the bcc tool of the same name.
+ *
+ * Copyright 2018 Netflix, Inc.
+ * Licensed under the Apache License, Version 2.0 (the "License")
+ *
+ * 08-Sep-2018	Brendan Gregg	Created this.
+ */
+
+BEGIN
+{
+	printf("Tracing cap_capable syscalls... Hit Ctrl-C to end.\n");
+	printf("%-9s %-6s %-6s %-16s %-4s %-20s AUDIT\n", "TIME", "UID", "PID",
+	    "COMM", "CAP", "NAME");
+	@cap[0] = "CAP_CHOWN";
+	@cap[1] = "CAP_DAC_OVERRIDE";
+	@cap[2] = "CAP_DAC_READ_SEARCH";
+	@cap[3] = "CAP_FOWNER";
+	@cap[4] = "CAP_FSETID";
+	@cap[5] = "CAP_KILL";
+	@cap[6] = "CAP_SETGID";
+	@cap[7] = "CAP_SETUID";
+	@cap[8] = "CAP_SETPCAP";
+	@cap[9] = "CAP_LINUX_IMMUTABLE";
+	@cap[10] = "CAP_NET_BIND_SERVICE";
+	@cap[11] = "CAP_NET_BROADCAST";
+	@cap[12] = "CAP_NET_ADMIN";
+	@cap[13] = "CAP_NET_RAW";
+	@cap[14] = "CAP_IPC_LOCK";
+	@cap[15] = "CAP_IPC_OWNER";
+	@cap[16] = "CAP_SYS_MODULE";
+	@cap[17] = "CAP_SYS_RAWIO";
+	@cap[18] = "CAP_SYS_CHROOT";
+	@cap[19] = "CAP_SYS_PTRACE";
+	@cap[20] = "CAP_SYS_PACCT";
+	@cap[21] = "CAP_SYS_ADMIN";
+	@cap[22] = "CAP_SYS_BOOT";
+	@cap[23] = "CAP_SYS_NICE";
+	@cap[24] = "CAP_SYS_RESOURCE";
+	@cap[25] = "CAP_SYS_TIME";
+	@cap[26] = "CAP_SYS_TTY_CONFIG";
+	@cap[27] = "CAP_MKNOD";
+	@cap[28] = "CAP_LEASE";
+	@cap[29] = "CAP_AUDIT_WRITE";
+	@cap[30] = "CAP_AUDIT_CONTROL";
+	@cap[31] = "CAP_SETFCAP";
+	@cap[32] = "CAP_MAC_OVERRIDE";
+	@cap[33] = "CAP_MAC_ADMIN";
+	@cap[34] = "CAP_SYSLOG";
+	@cap[35] = "CAP_WAKE_ALARM";
+	@cap[36] = "CAP_BLOCK_SUSPEND";
+	@cap[37] = "CAP_AUDIT_READ";
+}
+
+kprobe:cap_capable
+{
+	$cap = arg2;
+	$audit = arg3;
+	time("%H:%M:%S  ");
+	printf("%-6d %-6d %-16s %-4d %-20s %d\n", uid, pid, comm, $cap,
+	    @cap[$cap], $audit);
+}
+
+END
+{
+	clear(@cap);
+}

tools/capable_example.txt

+Demonstrations of capable, the Linux bpftrace/eBPF version.
+
+
+capable traces calls to the kernel cap_capable() function, which does security
+capability checks, and prints details for each call. For example:
+
+# capable.bt
+TIME      UID    PID    COMM             CAP  NAME                 AUDIT
+22:11:23  114    2676   snmpd            12   CAP_NET_ADMIN        1
+22:11:23  0      6990   run              24   CAP_SYS_RESOURCE     1
+22:11:23  0      7003   chmod            3    CAP_FOWNER           1
+22:11:23  0      7003   chmod            4    CAP_FSETID           1
+22:11:23  0      7005   chmod            4    CAP_FSETID           1
+22:11:23  0      7005   chmod            4    CAP_FSETID           1
+22:11:23  0      7006   chown            4    CAP_FSETID           1
+22:11:23  0      7006   chown            4    CAP_FSETID           1
+22:11:23  0      6990   setuidgid        6    CAP_SETGID           1
+22:11:23  0      6990   setuidgid        6    CAP_SETGID           1
+22:11:23  0      6990   setuidgid        7    CAP_SETUID           1
+22:11:24  0      7013   run              24   CAP_SYS_RESOURCE     1
+22:11:24  0      7026   chmod            3    CAP_FOWNER           1
+22:11:24  0      7026   chmod            4    CAP_FSETID           1
+22:11:24  0      7028   chmod            4    CAP_FSETID           1
+22:11:24  0      7028   chmod            4    CAP_FSETID           1
+22:11:24  0      7029   chown            4    CAP_FSETID           1
+22:11:24  0      7029   chown            4    CAP_FSETID           1
+22:11:24  0      7013   setuidgid        6    CAP_SETGID           1
+22:11:24  0      7013   setuidgid        6    CAP_SETGID           1
+22:11:24  0      7013   setuidgid        7    CAP_SETUID           1
+22:11:25  0      7036   run              24   CAP_SYS_RESOURCE     1
+22:11:25  0      7049   chmod            3    CAP_FOWNER           1
+22:11:25  0      7049   chmod            4    CAP_FSETID           1
+22:11:25  0      7051   chmod            4    CAP_FSETID           1
+22:11:25  0      7051   chmod            4    CAP_FSETID           1
+[...]
+
+This can be useful for general debugging, and also security enforcement:
+determining a whitelist of capabilities an application needs.
+
+The output above includes various capability checks: snmpd checking
+CAP_NET_ADMIN, run checking CAP_SYS_RESOURCES, then some short-lived processes
+checking CAP_FOWNER, CAP_FSETID, etc.
+
+To see what each of these capabilities does, check the capabilities(7) man
+page and the kernel source.
+
+
+There is another version of this tool in bcc: https://github.com/iovisor/bcc
+The bcc version provides options to customize the output.