From 99170e0d765b79e48cca5ddee0d80194e0567613 Mon Sep 17 00:00:00 2001 From: Cosmin Cojocar Date: Thu, 31 Oct 2019 11:56:17 +0100 Subject: [PATCH] Update the README with some details about the CWE mapping (#407) * Fix some typos in the README file Signed-off-by: Cosmin Cojocar * Update the README with some details about the CWE mapping Signed-off-by: Cosmin Cojocar --- README.md | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index ea39ad3..91652b7 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,8 @@ Inspects source code for security problems by scanning the Go AST. ## License -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. +Licensed under the Apache License, Version 2.0 (the "License"). +You may not use this file except in compliance with the License. You may obtain a copy of the License [here](http://www.apache.org/licenses/LICENSE-2.0). ## Project status @@ -59,7 +59,7 @@ go get github.com/securego/gosec/cmd/gosec Gosec can be configured to only run a subset of rules, to exclude certain file paths, and produce reports in different formats. By default all rules will be run against the supplied input files. To recursively scan from the current -directory you can supply './...' as the input argument. +directory you can supply `./...` as the input argument. ### Available rules @@ -96,8 +96,8 @@ directory you can supply './...' as the input argument. ### Selecting rules -By default gosec will run all rules against the supplied file paths. It is however possible to select a subset of rules to run via the '-include=' flag, -or to specify a set of rules to explicitly exclude using the '-exclude=' flag. +By default, gosec will run all rules against the supplied file paths. It is however possible to select a subset of rules to run via the `-include=` flag, +or to specify a set of rules to explicitly exclude using the `-exclude=` flag. ```bash # Run a specific set of rules @@ -106,6 +106,9 @@ $ gosec -include=G101,G203,G401 ./... # Run everything except for rule G303 $ gosec -exclude=G303 ./... ``` +### CWE Mapping + +Every issue detected by `gosec` is mapped to a [CWE (Common Weakness Enumeration)](http://cwe.mitre.org/data/index.html) which describes in more generic terms the vulnerability. The exact mapping can be found [here](https://github.com/securego/gosec/blob/53be8dd8644ee48802114178cff6eb7e29757414/issue.go#L49). ### Configuration @@ -140,7 +143,7 @@ of functions which will be skipped when auditing the not checked errors: ### Dependencies -gosec will fetch automatically the dependencies of the code which is being analyzed when go modules are turned on (e.g.` GO111MODULE=on`). If this is not the case, +gosec will fetch automatically the dependencies of the code which is being analyzed when go module is turned on (e.g.` GO111MODULE=on`). If this is not the case, the dependencies need to be explicitly downloaded by running the `go get -d` command before the scan. ### Excluding test files and folders @@ -162,7 +165,8 @@ Also additional folders can be excluded as follows: ### Annotating code -As with all automated detection tools there will be cases of false positives. In cases where gosec reports a failure that has been manually verified as being safe it is possible to annotate the code with a '#nosec' comment. +As with all automated detection tools, there will be cases of false positives. In cases where gosec reports a failure that has been manually verified as being safe, +it is possible to annotate the code with a `#nosec` comment. The annotation causes gosec to stop processing any further nodes within the AST so can apply to a whole block or more granularly to a single expression. @@ -183,10 +187,12 @@ func main(){ ``` -When a specific false positive has been identified and verified as safe, you may wish to suppress only that single rule (or a specific set of rules) within a section of code, while continuing to scan for other problems. To do this, you can list the rule(s) to be suppressed within the `#nosec` annotation, e.g: `/* #nosec G401 */` or `// #nosec G201 G202 G203 ` +When a specific false positive has been identified and verified as safe, you may wish to suppress only that single rule (or a specific set of rules) +within a section of code, while continuing to scan for other problems. To do this, you can list the rule(s) to be suppressed within +the `#nosec` annotation, e.g: `/* #nosec G401 */` or `// #nosec G201 G202 G203` -In some cases you may also want to revisit places where #nosec annotations -have been used. To run the scanner and ignore any #nosec annotations you +In some cases you may also want to revisit places where `#nosec` annotations +have been used. To run the scanner and ignore any `#nosec` annotations you can do the following: ```bash @@ -244,7 +250,7 @@ The released version of the tool is available in the `dist` folder. The build in gosec - Golang security checker gosec analyzes Go source code to look for common programming mistakes that -can lead to security problems. + VERSION: 1.0.0 GIT TAG: v1.0.0 @@ -262,7 +268,7 @@ make image ``` You can run the `gosec` tool in a container against your local Go project. You just have to mount the project -into a volume as follow: +into a volume as follows: ```bash docker run -it -v /:/ securego/gosec //... @@ -284,4 +290,4 @@ You can invoke now the `go generate` in the root of the project: go generate ./... ``` -This will generate the `rules/tls_config.go` file with will contain the current ciphers recommendation from Mozilla. +This will generate the `rules/tls_config.go` file which will contain the current ciphers recommendation from Mozilla.