ai-code-sec-audit

ai-code-sec-audit is a lightweight Python package and CLI that runs Bandit and Semgrep, normalizes findings into a stable JSON schema, computes a deterministic score, and writes a reproducible report.

Install

pip install ai-code-sec-audit

CLI usage

ai-code-sec-audit audit path/to/file.py -o report.json
ai-code-sec-audit audit path/to/dir -o report.json -f high

Options use short flags:

• -o: output JSON path (required)
• -p: profile (default: default)
• -f: fail threshold (critical|high|medium|low|info)
• -P: pretty-print JSON

Python API

from ai_code_sec_audit import audit_path

report = audit_path("path/to/file.py", profile="default", fail_on="high")
print(report.summary.score)

Output schema

Canonical JSON report fields:

• meta: tool_version, timestamp, target, profile, how_to_reproduce
• summary: score, total_findings, counts, should_fail
• findings[]: tool, rule_id, title, description, severity, confidence, cwe, file, start_line, end_line, fingerprint, references

Reproducible command

meta.how_to_reproduce contains the exact command with resolved target/output paths and selected flags to reproduce the same report.

Sample JSON snippet

{
  "meta": {
    "tool_version": "0.1.0",
    "target": "/abs/path/examples/vuln_python/app.py",
    "profile": "default",
    "how_to_reproduce": "ai-code-sec-audit audit /abs/path/examples/vuln_python/app.py -o /abs/path/report.json -p default"
  },
  "summary": {
    "score": 86,
    "total_findings": 2,
    "counts": {
      "critical": 0,
      "high": 1,
      "medium": 1,
      "low": 0,
      "info": 0
    },
    "should_fail": true
  }
}

Scoring

Score starts at 100 and deducts:

• critical: 20
• high: 10
• medium: 4
• low: 1
• info: 0

Final score is clamped to 0..100.

Fail-on behavior

• critical: fail if any critical findings
• high: fail if any critical/high
• medium: fail if any critical/high/medium
• low: fail if any critical/high/medium/low
• info: fail if any finding exists

CLI exits with status code 2 when threshold is met.

Scanner behavior

• Bandit command:
  • directory: bandit -r <target> -f json
  • file: bandit <target> -f json
• Semgrep command: semgrep --config auto --json <target>
• If scanner binaries are missing, warnings are printed and scanning continues.

Limitations (v0.1.0)

• No HTML reports
• No SARIF output
• Only Bandit + Semgrep are supported
• No advanced configuration system

Roadmap

• Additional scanner integrations
• Config file support
• Optional report enrichments and diff mode

Sample run artifacts

This repository includes sample-run inputs and outputs:

• Vulnerable input: examples/vuln_python/app.py
• Safer input: examples/safe_python/app.py
• Reproducible run script: examples/sample_runs/run_samples.sh
• Captured run logs: examples/sample_runs/vuln_run.txt, examples/sample_runs/safe_run.txt
• Generated reports: examples/sample_runs/vuln_report.json, examples/sample_runs/safe_report.json

Run from repo root:

./examples/sample_runs/run_samples.sh

Publish to PyPI

This project is now configured for PyPI publishing with:

• package metadata in pyproject.toml
• reproducible sdist + wheel builds via hatchling
• a GitHub Actions workflow at .github/workflows/publish.yml that uploads on release

One-time setup

1. Create a project on PyPI named ai-code-sec-audit.
2. In the PyPI project settings, enable Trusted Publishing for your GitHub repository and the workflow file .github/workflows/publish.yml.
3. Update project.urls in pyproject.toml if your repository URL differs.

Release flow (recommended)

1. Bump src/ai_code_sec_audit/version.py.
2. Commit and tag a release in GitHub.
3. Publish a GitHub Release (or run the workflow manually).
4. The workflow builds, validates, and uploads the package to PyPI.

Manual upload (fallback)

python -m pip install --upgrade build twine
python -m build
twine check dist/*
twine upload dist/*

Development

ruff check .
ruff format .
mypy src
pytest
python -m build
twine check dist/*

License

MIT.