144 lines
4.5 KiB
Markdown
144 lines
4.5 KiB
Markdown
# Security Audit Toolchain
|
|
|
|
GovOPlaN uses a free/open-source-first audit toolchain that can run locally,
|
|
inside a container, and in Gitea Actions.
|
|
|
|
## Tools
|
|
|
|
- Semgrep: multi-language SAST, with GovOPlaN-specific local rules plus
|
|
explicit public registry rulesets in CI/full runs.
|
|
- Bandit: Python AST security checks.
|
|
- Ruff `S` rules: fast flake8-bandit-compatible Python security linting.
|
|
- Gitleaks: committed-secret scanning.
|
|
- Trivy: filesystem dependency, secret, and misconfiguration scanning.
|
|
- pip-audit and npm audit: package vulnerability scanning from dependency
|
|
manifests/locks.
|
|
- OSV-Scanner: recursive dependency vulnerability scan in full mode.
|
|
- jscpd: duplicated-code reports in full mode.
|
|
- Radon/Xenon: Python complexity reports and thresholds in full mode.
|
|
|
|
## Local Usage
|
|
|
|
Build and run the toolbox from this repository:
|
|
|
|
```bash
|
|
cd /mnt/DATA/git/govoplan
|
|
tools/checks/security-audit/run.sh --mode ci --scope current
|
|
```
|
|
|
|
Scan all sibling GovOPlaN repositories under `/mnt/DATA/git`:
|
|
|
|
```bash
|
|
cd /mnt/DATA/git/govoplan
|
|
tools/checks/security-audit/run.sh --mode full --scope govoplan
|
|
```
|
|
|
|
Reports are written to `audit-reports/`, which is intentionally ignored by git.
|
|
|
|
The wrapper tags the toolbox image by a fingerprint of the Dockerfile and
|
|
`requirements-audit.txt`. If those inputs have not changed, subsequent runs reuse
|
|
the existing local image instead of reinstalling all tools. The stable alias is
|
|
`govoplan/security-audit:local` unless `SECURITY_AUDIT_IMAGE` is set.
|
|
|
|
Force a cached rebuild:
|
|
|
|
```bash
|
|
tools/checks/security-audit/run.sh --mode ci --scope current --rebuild
|
|
```
|
|
|
|
Refresh from upstream base images and package ranges:
|
|
|
|
```bash
|
|
tools/checks/security-audit/run.sh --mode ci --scope current --update
|
|
```
|
|
|
|
Build or refresh the toolbox without running an audit:
|
|
|
|
```bash
|
|
tools/checks/security-audit/run.sh --mode quick --scope current --build-only
|
|
tools/checks/security-audit/run.sh --mode quick --scope current --update --build-only
|
|
```
|
|
|
|
## Modes
|
|
|
|
- `quick`: local Semgrep rules, Bandit, Ruff security rules, Gitleaks.
|
|
- `ci`: quick plus Semgrep public registry rulesets, Trivy, pip-audit, npm audit.
|
|
- `full`: ci plus OSV-Scanner, jscpd, Radon, and Xenon.
|
|
|
|
## Gating
|
|
|
|
The initial Gitea workflow runs in report-only mode:
|
|
|
|
```bash
|
|
SECURITY_AUDIT_FAIL_ON_FINDINGS=0
|
|
```
|
|
|
|
This avoids blocking every push while the first baseline is reviewed. After the
|
|
baseline is clean, switch the workflow to:
|
|
|
|
```bash
|
|
SECURITY_AUDIT_FAIL_ON_FINDINGS=1
|
|
```
|
|
|
|
or run locally with:
|
|
|
|
```bash
|
|
tools/checks/security-audit/run.sh --mode ci --scope current --strict
|
|
```
|
|
|
|
## Audit Burndown Workflow
|
|
|
|
Treat Gitea issues as the active audit state. A full GovOPlaN audit should
|
|
produce one tracker issue in `add-ideas/govoplan` and child issues in the
|
|
repository that owns each fix.
|
|
|
|
Use the tracker issue for:
|
|
|
|
- report path, timestamp, mode, and scope
|
|
- scanner counts by category
|
|
- clean scanners and resolved findings
|
|
- links to child issues
|
|
- the next audit run target
|
|
|
|
Use child issues for concrete code or configuration changes. Apply
|
|
`source/security-audit` to every issue created from a report, then add the
|
|
most specific audit label:
|
|
|
|
- `audit/quick-fix`: narrow direct remediation
|
|
- `audit/structural`: behavior or architecture needs review
|
|
- `audit/complexity`: Radon/Xenon maintainability finding
|
|
- `audit/duplication`: jscpd duplication finding
|
|
- `audit/false-positive`: reviewed narrow false positive or accepted risk
|
|
- `audit/needs-design`: human decision needed before implementation
|
|
|
|
Keep active implementation status in issues instead of committing generated
|
|
audit reports. `audit-reports/` is ignored; quote the report directory and the
|
|
important scanner counts in the tracker issue.
|
|
|
|
## Image Freshness
|
|
|
|
The regular `Security Audit` workflow reuses the fingerprinted toolbox image
|
|
when the Docker daemon is persistent, which is the normal case for the
|
|
self-hosted Gitea runner using the host Docker socket. The separate
|
|
`Security Audit Toolbox Update` workflow runs weekly with
|
|
`SECURITY_AUDIT_UPDATE=1`; it pulls current base images and re-resolves the
|
|
allowed tool version ranges into a refreshed local image.
|
|
|
|
## Direct Host Usage
|
|
|
|
The container is the recommended path. For direct host usage, install the Python
|
|
tools first:
|
|
|
|
```bash
|
|
cd /mnt/DATA/git/govoplan
|
|
python -m venv .venv
|
|
./.venv/bin/python -m pip install -r requirements-audit.txt
|
|
```
|
|
|
|
Then install the non-Python tools (`gitleaks`, `trivy`, `osv-scanner`, `jscpd`)
|
|
through the host package manager or vendor instructions and run:
|
|
|
|
```bash
|
|
tools/checks/check-security-audit.sh --mode quick --scope current
|
|
```
|