Overhaul READMEs for Static Analysis analysers
Problem to solve
The READMEs for groupstatic analysis analysers should be reviewed and improved. Some READMEs contain outdated and/or misleading information which is sure to trip-up new contributors.
Most analysers behave similarly, so much of the README content can be extracted into a common location and linked. A good home for this would be https://gitlab.com/gitlab-org/secure/tools/analyzer-scripts
For some of the more complex analysers, we should include an overview of how they're structured and any quirks to look out for, within the README of that analyser.
Proposal
-
Modify the README of the Analyzer Scripts repo to include information common to all/most analysers. I've started an MR in MobSF which adds a lot of generic build and run instructions; once that MR is approved we can move the content to Analyzer Scripts. -
For each analyser below, update its README to follow the common template. Add analyser-specific information where necessary. -
semgrep: https://gitlab.com/gitlab-org/security-products/analyzers/semgrep - Be sure to mention how the rules work; testing, releasing etc.
-
brakeman: https://gitlab.com/gitlab-org/security-products/analyzers/brakeman -
kubesec: https://gitlab.com/gitlab-org/security-products/analyzers/kubesec -
mobsf: https://gitlab.com/gitlab-org/security-products/analyzers/mobsf -
Mention that we spin up a Python server internally -
Mention the convoluted matching logic we've had to add to support nested projects
-
-
phpcs-security-audit: https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit -
pmd-apex: https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex -
security-code-scan: https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan -
sobelow: https://gitlab.com/gitlab-org/security-products/analyzers/sobelow -
spotbugs: https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs -
Mention how the JDKs are installed and configured in the big script
-
-
secrets: https://gitlab.com/gitlab-org/security-products/analyzers/secrets -
nodejs-scan: https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan
-
The common template README for each analyser could look like the following:
# <analyser name>
<analyser name> performs (SAST|Secret Detection|IaC) scanning on repositories containing the following code:
- <language A>
- <language B>
The analyzer wraps <upstream project> and is written in Go. It's structured similarly to other Static Analysis analyzers because it uses the shared [command](https://gitlab.com/gitlab-org/security-products/analyzers/command) package.
The analyzer is built and published as a Docker image in the GitLab Container Registry associated with this repository. You would typically use this analyzer in the context of a [SAST](https://docs.gitlab.com/ee/user/application_security/sast/), [IaC](https://docs.gitlab.com/ee/user/application_security/iac_scanning/), or [Secret Detection](https://docs.gitlab.com/ee/user/application_security/secret_detection/) job in your CI/CD pipeline. However, if you're contributing to the analyzer or you're needing to debug a problem, you can run, debug, and test locally using Docker.
For instructions on local development, refer to the [README in Analyzer Scripts](https://gitlab.com/gitlab-org/secure/tools/analyzer-scripts).
## Contributing
Contributions are welcome, see [`CONTRIBUTING.md`](CONTRIBUTING.md) for more details.
## License
This code is distributed under the MIT Expat license, see the [LICENSE](LICENSE) file.
Edited by Ahmed Hemdan