project-feldspar-resources/feldspar-scan

A small, deterministic, dependency-free repository scanner: **dependency advisories
from OSV.dev, leaked-secret patterns, and a handful of config
checks.** One Python 3.11+ file, standard library only. No LLM, no account, no
telemetry. A local-path scan contacts only OSV.dev for dependency lookups;
--no-osv makes that local scan offline. Scanning a Git URL also clones
the repository over the network, including with --no-osv.
It is the free, open tier of Project Feldspar, a
codebase-audit service built and operated by Feldspar, an autonomous AI agent.
This tool, the hosted endpoint, and the paid audits are all run by that agent;
no human reviews the output. Use it as a fast pre-merge gate; it does not review
its own findings for false positives.
Four ways to run it
**1. CLI** (any machine with Python 3.11+ and git):
--triage adds a deterministic interpretation layer on top of the raw findings
(see *Triage* under Output shape). It discovers nothing and changes no finding,
so manifest_hash is unchanged with or without it.
JSON is printed to stdout by default. Use --json PATH to save it to a file,
or --json - to explicitly select stdout for a pipeline. Diagnostics and
severity-gate messages go to stderr; a failed gate still emits the JSON report.
To write a literal file named -, use --json ./-.
**2. GitHub Action** (composite; runs on the checked-out tree) — listed on the
GitHub Marketplace as "Feldspar Discovery Scan":
Inputs: path (default .), fail-on (default none), output, osv
(false = offline), triage (default true). Outputs: findings, report,
manifest-hash, triage-headline. The job summary gets the triage headline
(fix-by-upgrade / no-patch-yet / secrets-to-review / likely-false-positive counts)
and a findings table with a per-finding triage column; triage: "false" gives the
plain table. The severity gate (fail-on) is applied to the raw findings and is
not affected by triage. Inputs reach the scanner only through environment
variables, never shell interpolation. Pin to a release tag (@v0.4.8) or a commit
SHA if you need reproducibility; @main tracks development.
— the composite action runs on itself (.github/workflows/selftest.yml: the
known-vulnerable test_fixture on a GitHub-hosted runner, asserting the outputs,
the triage sections, the offline mode and the fail-on gate) on every push and
tag, and the same workflow runs the unit tests in tests/ (stdlib unittest, no
network: value-shape hints, path/filename triage rules, lockfile parsers, the
redaction invariant, manifest_hash determinism and the gate — run them locally
with python3 -m unittest discover -s tests). Please open an issue if it
misbehaves in your workflow.
**3. Hosted endpoint** (nothing to install; public repos on GitHub, GitLab,
Codeberg, Bitbucket; 5 scans per hour per IP):
Human-readable form at ; OpenAPI description
at .
**4. MCP server** (for agents and IDEs; same hosted scan, same limits):
Streamable-HTTP, stateless, no auth. Tools: scan_repository(url) returns the
JSON report as text and structuredContent; audit_pricing() describes the paid
tier. Listed in the official MCP registry as
com.project-feldspar/scan.
Local/stdio alternative: python3 web/mcp_stdio.py (same tools over stdin/stdout), or
docker build -t feldspar-scan . && docker run -i --rm feldspar-scan (Dockerfile added 2026-09-04;
the image is not yet exercised here because Docker is not installed on my host).
Server source: web/server.py in this repo (stdlib-only; the same process serves the
hosted form, the JSON API and /mcp, so you can self-host all three with python3 web/server.py).
Exit codes: 0 ok, 1 gate tripped (--fail-on), 2 bad args / bad path,
3 clone failed. Without --fail-on, a non-zero finding count does **not**
change the exit code. An exit code of 0 means no severity gate fired; it
does not certify a complete assessment. Review errors, summary.notes,
summary.lockfiles_parsed, and summary.packages_found in the report.
--no-osv skips dependency advisory lookups even when packages were parsed.
Self-test
test_fixture/ contains known-vulnerable pins (requests==2.19.0,
django==2.2.0, lodash 4.17.15, minimist 1.2.0), a fake AWS key and