[vsn411]

Summary

Three things a visitor needs: find the project, see it work in 30 seconds, and drop it into CI.

Get found

• pyproject.toml: keyword-rich PyPI summary (“AI security review CLI: SAST, secret scanning, SCA, threat modeling …”), more classifiers, keywords, and [project.urls] (homepage, docs, source, changelog, issues, CI guide).
• README now uses absolute image and link URLs so it renders correctly on PyPI.
• (Done outside this PR: repo description, homepage and 20 topics on GitHub.)

Convert in 30 seconds

• A real terminal GIF leads the README: secfoo run against OWASP/NodeGoat, the results table, one finding, SARIF export. scripts/terminal_gif.py renders it from the captured output, so no terminal recorder is needed and the text is the real output.
• First command is uvx secfoo run --skill sast --skill secret-scanning --target …. Behaviour change: without --agent and without a configured default, secfoo run now uses the first agent CLI found on PATH, or the api agent when OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY is already set, instead of assuming claude. It prints which one it picked. Falls back to claude when nothing is found (same error as before). Four tests added.
• examples/sample-output/nodegoat/: the unedited SAST and secret-scanning reports, transcript, SARIF and JSONL from that run (Claude Code, --depth quick, 4 min 12 s, $3.73, 9 High findings).

Get into CI

• action.yml: composite GitHub Action. Installs from PyPI, runs the skills, exports SARIF, uploads to code scanning (github/codeql-action/upload-sarif, pinned), writes a job summary, exposes exit-code / critical / high / medium / low / cost-usd outputs, and applies secfoo's exit code after the upload so findings land in the Security tab even when the gate fails. Optional install-agent-cli: claude|codex|gemini|copilot.
• .pre-commit-hooks.yaml: secfoo (configurable) and secfoo-secrets hooks.
• docs/CI.md + examples/ci/ (GitHub Actions with and without the action, GitLab CI, pre-commit). REFERENCE.md gains uvx / pipx install lines and pointers.

Follow-ups (not in this PR)

• Publish the action to the Marketplace: create a release from a tag and tick “Publish this Action to the GitHub Marketplace” (needs the action name to be unique; it is “secfoo AI Security Review”).
• Set the social preview image under Settings → General (no API for it).
• ghcr.io/rakfortltd/secfoo is referenced by the README/docs but no image is published yet; the private release workflow owns that.
• SARIF: a finding whose location lists several files (e.g. F12 in the sample) is exported with the whole list as one artifactLocation.uri; worth splitting into multiple locations.

Test plan

• pytest tests: 1265 passed; tests/test_sensor/test_python_probe.py::test_sensor_dying_mid_run_drops_events_without_blocking fails identically on untouched main on macOS (pre-existing).
• ruff check error count unchanged for the edited files (lint is advisory in CI).
• uvx secfoo@0.3.1 --help works from PyPI.
• Real run that produced the sample output and GIF.
• After merge: run the action from a test repo once (uses: secfoo-com/secfoo@main) to confirm the SARIF upload path end to end.

🤖 Generated with Claude Code