github.com/google/capslock@v0.2.3-0.20240517042941-dac19fc347c0/docs/capabilities.md

github.com/google/capslock@v0.2.3-0.20240517042941-dac19fc347c0/docs/capabilities.md (about)

1 A taxonomy of implied capabilities is central to the Capslock tool's
2 analysis and reporting. This document describes how these capabilities
3 are defined, what they represent and how they broadly map to concrete
4 library calls.
5
6 **NB. until the capslock-1.0 release, capability names and mappings are
7 not stable and are subject to change.** Feedback on the capabilities and
8 how they are assigned is very welcome.
9
10 The capabilities that Capslock reports are defined in the
11 `src/proto/capability.proto` file, specifically the `Capability`
12 enum. The `src/interesting/interesting.go` file contains the mappings
13 from library modules and calls to these capabilities.
14
15 Capability mappings are performed first at the *package* level
16 and then at the *function* level. For example, everything in the
17 [os](https://pkg.go.dev/os) package is by default assumed to
18 have the `CAPABILITY_OPERATING_SYSTEM` capability but specific
19 functions override this with other capabilities, such as the
20 [os.Chown()](https://pkg.go.dev/os#Chown) function being assigned
21 `CAPABILITY_FILES`.
22
23 In addition to mapping packages and library calls to
24 capabilities, Capslock may also assign capabilities based
25 on the use of particular types in the code itself, such as
26 [unsafe.Pointer](https://pkg.go.dev/unsafe#Pointer) or
27 [reflect.Value](https://pkg.go.dev/reflect#Value).
28
29 ## Capabilities
30
31 The following section describe the purpose and intent of the
32 capabilities that Capslock reports in analyzed code. These descriptions
33 are not meant to be exhaustive.
34
35 ### CAPABILITY_UNSPECIFIED
36
37 This is the default (zero) value for uninitialized capabilities.
38
39 It is also explicitly assigned to functions when the module they reside
40 in has a catch-all capability applied that must be cleared to allow
41 deeper analysis.
42
43 For example, the entire [os/exec](https://pkg.go.dev/os/exec) package
44 has the catch-all `CAPABILITY_EXEC` capability assigned, but it defines
45 an internal `exec.wrappedError` type that may wrap another error. Since
46 the wrapped error may be an arbitrary type that fulfils the `error`
47 interface , calling into it via `(exec.wrappedError).Error` may invoke
48 additional capabilities. Clearing the module-level capability with
49 `CAPABILITY_UNSPECIFIED` allows the analysis to continue and potentially
50 find these cases.
51
52 ### CAPABILITY_SAFE
53
54 This value is used to explicitly allowlist particular functions or
55 modules. Unlike assigning `CAPABILITY_UNSPECIFIED`, assigning this
56 value explicitly terminates further analysis.
57
58 ### CAPABILITY_FILES
59
60 Represents the ability to read or modify the file system, including
61 reading or writing files, changing file permissions or ownership,
62 creating symbolic or hard links, creating or deleting directories and
63 files.
64
65 ### CAPABILITY_NETWORK
66
67 Represents the ability to interact with the network, including making
68 connections to other hosts, connecting to local network sockets,
69 and listening for connections.
70
71 ### CAPABILITY_RUNTIME
72
73 Represents the ability to read or modify sensitive information from the
74 Go runtime itself. This includes the ability to terminate a goroutine,
75 change the garbage collector, stack or threading parameters, or change
76 the runtime's behavior around panicking on memory faults.
77
78 ### CAPABILITY_READ_SYSTEM_STATE
79
80 Represents the ability to read information about the system state and
81 execution environment, including reading environment variables and their
82 contents, obtaining a list of available network interfaces and their
83 addresses, or reading process information such as the current working
84 directory, process ID or user.
85
86 ### CAPABILITY_MODIFY_SYSTEM_STATE
87
88 Represents the ability to modify the state of the system or execution
89 environment, such as changing the process' working directory, setting
90 environment variables, or modifying the disposition of
91 [os/signal](https://pkg.go.dev/os/signal) handlers.
92
93 ### CAPABILITY_OPERATING_SYSTEM
94
95 This capability acts as a catch-all for operations in the
96 [os](https://pkg.go.dev/os) package that are not explicitly categorized.
97
98 ### CAPABILITY_SYSTEM_CALLS
99
100 This capability represents the ability to make direct system calls and
101 is applied at module level to a number of packages. It generally implies
102 the ability to execute arbitrary code.
103
104 ### CAPABILITY_ARBITRARY_EXECUTION
105
106 Represents the use of operations that invoke assembler code or may
107 violate Go's type safety (e.g. via the [unsafe](https://pkg.go.dev/unsafe)
108 package) and thereby may invoke arbitrary behavior. Capslock cannot
109 effectively analyze such code.
110
111 ### CAPABILITY_CGO
112
113 Identifies calls that execute native code via Go's
114 [Cgo](https://pkg.go.dev/cmd/cgo) mechanism. Capslock cannot analyze
115 beyond this boundary.
116
117 ### CAPABILITY_UNANALYZED
118
119 Identifies situations where Capslock could not effectively analyze a
120 call path due to limitations in the tool itself.
121
122 ### CAPABILITY_UNSAFE_POINTER
123
124 Identifies code that uses `unsafe.Pointer`. This type may be used
125 to violate Go's type safety and could potentially be used to invoke
126 arbitrary behavior that Capslock is unable to effectively analyze.
127
128 ### CAPABILITY_REFLECT
129
130 Represents the use of reflection via the
131 [reflect](https://pkg.go.dev/reflect) package.
132
133 ### CAPABILITY_EXEC
134
135 Represents the ability to execute other programs, e.g. via the
136 [os/exec](https://pkg.go.dev/os/exec) package.