add-ideas/govoplan
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
342582645b6f7f93fcf365927e91e97d44eeac2c
govoplan/docs/SECURITY_AUDIT.md

4.5 KiB
Raw Blame History

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:

cd /mnt/DATA/git/govoplan
tools/checks/security-audit/run.sh --mode ci --scope current

Scan all sibling GovOPlaN repositories under /mnt/DATA/git:

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:

tools/checks/security-audit/run.sh --mode ci --scope current --rebuild

Refresh from upstream base images and package ranges:

tools/checks/security-audit/run.sh --mode ci --scope current --update

Build or refresh the toolbox without running an audit:

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:

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:

SECURITY_AUDIT_FAIL_ON_FINDINGS=1

or run locally with:

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:

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:

tools/checks/check-security-audit.sh --mode quick --scope current