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

     1  # Caveats
     2  
     3  ### False Positives
     4  
     5  The tool analyzes a library and its dependencies and reports which functions
     6  call, either directly or transitively, standard library functions that have
     7  notable capabilities, such as opening a file or opening a network connection.
     8  
     9  However, each chain of calls reported by the tool may not necessarily occur in
    10  practice.  For example, a function may contain an if statement where
    11  [os.ReadFile](https://pkg.go.dev/os#ReadFile) is called if one of the
    12  function's parameters is `true`.  The static analysis assumes that every
    13  block of code within a function might be executed, so any caller of this
    14  function would be reported to have the `FILES` capability via its
    15  dependencies, even if it always passed `false` as the relevant argument.
    16  
    17  Similarly, when a method of an interface value is called, the analysis will
    18  determine which runtime types that interface value might have, but this may
    19  include types which do not occur in practice in the chain of function calls
    20  that is reported.
    21  
    22  ### Reflection
    23  
    24  The [reflect](https://pkg.go.dev/reflect) library allows the creation of
    25  objects and types which are difficult for the analysis to follow.  For some
    26  uses of reflect, the analysis can determine that no additional capabilities
    27  are produced.  Otherwise, the tool treats the use of reflect as another
    28  capability and informs the user of it, so that capabilities are not missed
    29  without any indication to the user.
    30  
    31  ### Calling other programs
    32  
    33  The packages [os/exec](https://pkg.go.dev/os/exec) and
    34  [plugin](https://pkg.go.dev/plugin) allow other programs to be loaded
    35  and run.  The analysis cannot determine what capabilities these might have, so
    36  it is reported to the user as a capability of its own.
    37  
    38  ### Unsafe
    39  
    40  Although most uses in practice of the [unsafe](https://pkg.go.dev/unsafe)
    41  library perform simple tasks, it is possible to use unsafe pointers to produce
    42  any behavior at all, by overwriting function pointers or code.  The tool
    43  treats use of unsafe pointers as a capability, and reports them to the user.
    44  
    45  ### Data Races
    46  
    47  Data races on variables of interface and slice type can produce arbitrary
    48  behavior, including calling library functions with any capability, without
    49  needing to use the unsafe library.  The tool does not inform users of writes to
    50  interfaces and slices that may cause a data race.
    51  
    52  ### go:linkname
    53  
    54  Capslock does not resolve the location of functions using a `//go:linkname`
    55  directive,  Calls to such functions will have the `ARBITRARY_EXECUTION`
    56  capability.
    57  
    58  See the [compiler
    59  documentation](https://pkg.go.dev/cmd/compile#hdr-Compiler_Directives) for more
    60  information about linkname directives.
    61  
    62  ### Cgo and Assembly
    63  
    64  Capslock cannot analyze C or assembly code.  Capslock will report calls to
    65  [cgo](https://pkg.go.dev/cmd/cgo) or assembly functions by reporting that
    66  the calling functions have the CGO or `ARBITRARY_EXECUTION` capabilities,
    67  respectively.
    68  
    69  ### Dependency Resolution
    70  
    71  Capslock can be used to investigate the capabilities of a library you have
    72  added as a dependency of your project, or which you are considering adding.
    73  When doing this, it is important that the Capslock tool reads the same source
    74  code that the `go` tool will read when building your project.
    75  
    76  The best way to achieve this is to run the tool from your project's directory.
    77  This ensures that issues like version selection, vendoring, and module file
    78  directives are resolved in the same way by `capslock` and `go`.
    79  
    80  If the library you are considering is not currently a dependency of your
    81  module, you can add it with the `go get` command.
    82  
    83  For example:
    84  ```sh
    85  $ go get golang.org/x/text/width
    86  
    87  $ capslock -packages=golang.org/x/text/width
    88  ```
    89  
    90  ### Build Constraints
    91  
    92  Go source files can contain a build constraint, which specifies a condition
    93  determining whether the file should be included in a build.  The constraint is
    94  a boolean expression involving build tags.
    95  
    96  See the relevant
    97  [go command documentation](https://pkg.go.dev/cmd/go#hdr-Build_constraints)
    98  for more information about build tags.
    99  
   100  The Capslock command-line tool will analyze the same set of files the `go
   101  build` command would.  Extra tags can be specified with the `-buildtags` flag,
   102  equivalent to the `-tags` flag for `go build`.  The `GOOS` and `GOARCH` for the
   103  analysis can also be specified with the `-goos` and `-goarch` flags,
   104  respectively.
   105  
   106  ### Logic Bugs
   107  
   108  Even when a library has the expected set of capabilities, there is of course no
   109  guarantee that it performs its intended task correctly.  A library function
   110  could return incorrect results, or never return at all.
   111  
   112  Even with careful human review of all code that is being imported, it can be
   113  difficult to catch logic bugs, especially any that are deliberately hidden.
   114  Some degree of trust in the authors is required for any software that is to be
   115  used for an important purpose.