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.

What it reads

Not read: composer.lock, Maven/Gradle, NuGet, Pipfile.lock, pyproject.toml, package.json. Matching is by exact file name (details under What it checks below). If none of these files is parsed, the report's summary.notes says so. Secret patterns run on text files (lockfiles, binaries and minified bundles are skipped); config checks cover committed .env files, Dockerfiles, docker-compose files, GitHub Actions workflows, .npmrc and .pypirc.

Four ways to run it

1. CLI (any machine with Python 3.11+ and git):

curl -fsSLO https://raw.githubusercontent.com/project-feldspar-resources/feldspar-scan/main/scan.py
python3 scan.py <local-repo-path-or-git-https-url> [--json out.json] [--no-osv] [--fail-on high] [--triage]

--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.

Use --no-triage to explicitly omit the interpretation layer (the default). When --triage and --no-triage are repeated, the last flag wins, so a caller can override a shared argument list. This omits both triage and triage_summary; raw findings, manifest_hash, output formatting and severity-gate behavior stay the same.

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 ./-. The equivalent inline form --json=PATH accepts a non-empty path, including --json=- for stdout. Quote the argument if the path contains spaces, for example --json="report folder/result=a.json"; equals signs within the path are preserved. An empty --json= is an argument error (exit 2) before scanning or cloning.

When --json PATH or --json=PATH is repeated, the last destination wins; earlier destinations are not opened for output or written. For example, --json unused.json --json=- prints only to stdout, while --json=- --json final.json writes only final.json. This also lets a wrapper's output destination be overridden. An invalid earlier --json= still exits 2; a later valid destination does not cancel the argument error.

For either spelling, a relative output path is resolved from the caller's working directory. For example, python3 scan.py ./repository --no-osv --json report.json writes ./report.json, not ./repository/report.json. Absolute output paths select that exact location. An existing destination is overwritten after the scan; it is not automatically excluded from scanning when it lies inside the target.

... View full README on GitHub