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

     1  # Using Capslock
     2  
     3  Install the Capslock command-line tool with the
     4  [go tool](https://pkg.go.dev/cmd/go#hdr-Compile_and_install_packages_and_dependencies):
     5  
     6  ``` shell
     7  go install github.com/google/capslock/cmd/capslock@latest
     8  ```
     9  
    10  Capslock can analyze packages that are part of your current module, or are
    11  dependencies of your current module.
    12  If necessary, use `go get` to make the package you wish to analyze a dependency
    13  of your current module.
    14  
    15  ``` shell
    16  go get package/to/analyze
    17  capslock -packages package/to/analyze
    18  ```
    19  
    20  If the package you wish to analyze isn't available you will get an error
    21  telling you to `go get` the package. You can also run `capslock` directly
    22  from the path of the package you want to analyze without needing to specify
    23  the `-packages` flag.
    24  
    25  If `capslock` isn't found or doesn't work, run `ls $GOBIN` to check that the
    26  capslock binary was installed properly and `which capslock` to check where the
    27  binary was installed.
    28  See the
    29  [go command documentation](https://pkg.go.dev/cmd/go#hdr-Compile_and_install_packages_and_dependencies)
    30  for more information about installing go packages.
    31  
    32  There are several output formats you can use in Capslock using the `-output`
    33  flag. For example, use `-output=v` to get more verbose output that includes
    34  example callpaths for all identified capabilities, or `-output=json` for json
    35  output enumerating each function with a capability that was identified by the
    36  analyzer, with an example call path for each one demonstrating that capability.
    37  
    38  
    39  ## List of capabilities
    40  
    41  See [capabilities documentation](capabilities.md) for a list of the capabilities the tool reports.
    42  
    43  ## Interpreting capability reports
    44  
    45  For many reports, the capabilities are unsurprising.  A library which connects
    46  to a service over the internet would be expected to have the `NETWORK`
    47  capability.
    48  
    49  For other reports, the practical consequences can be less clear.  For example,
    50  most uses of the `reflect` package have a simple purpose such as reading fields
    51  from a value with an arbitrary struct type.  But `reflect` can also be used to
    52  invoke arbitrary functions.  The static analysis is unable to determine the
    53  behavior of all code using reflect, so it falls back to reporting to the user
    54  that the code has the `REFLECT` capability.  Users can then inspect the
    55  functions the analysis points to if they wish.
    56  
    57  ## Flags
    58  
    59  Other than the `-packages` flag for setting the path for the packages to
    60  analyze, there are several other options for running Capslock.
    61  
    62  ### `-output`
    63  
    64  The `-output` flag lets you select what level of detail and format you want the
    65  output to be in. If the provided flag doesn't match any of the options, it
    66  defaults to give a short human-readable report on what the list of identified
    67  capabilities are.
    68  
    69  Accepted values for this flag include:
    70  
    71  1. `v` or `verbose` for a longer human-readable output including example
    72     callpaths.
    73  1. `j` or `json` for a machine-readable json output including paths to all
    74     capabilities.
    75  1. `compare` plus an additional argument specifying the location of a capability
    76     file. This requires that you have already run Capslock on a previous version
    77     of the package, and written the output in json format to a file - passing the
    78     file location with this flags lets you identify which of the capabilities
    79     changed between package version.
    80  
    81  ### Other flags
    82  
    83  1. `-noisy` will expand the analysis of functions with `CAPABILITY_UNANALYZED`
    84     to report the possible capabilities of these functions. Can result in
    85     spurious capabilities.
    86  1. `-template` allows you to specify an alternative template for printing the
    87     output.
    88  1. `-goos` and `-goarch` allow you to set to GOOS and GOARCH values for use when
    89     loading packages.
    90  1. `-buildtags` is used for setting build tags that are used in loading
    91     packages.
    92