Feldspar free repository security scan

feldspar-scan

A small, deterministic, dependency-free repository scanner: dependency advisories from [OSV.dev](https://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 [--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. Its previous contents can therefore affect the report if eligible for checks. Save reports outside the target to avoid scanning earlier output.

Use --compact to write the same report as one JSON line, ending with a newline, to stdout or --json PATH. Use --pretty to explicitly select the default two-space indented JSON. Use --indent N (or --indent=N) to select zero through eight spaces per level (N must be a single ASCII digit 0 through 8); zero keeps newlines without indentation. Use --tab-indent for one tab per JSON nesting level. The last --compact, --pretty, --indent N, or --tab-indent flag wins. Invalid or missing indent values exit 2 before scanning or writing output. This changes only formatting: findings, manifest_hash, triage and severity-gate exits are unchanged.

Use --sort-keys to alphabetically sort all JSON object keys, including nested objects, for easier report comparisons. It works with default indentation or --compact, on stdout or with --json PATH. It changes only serialization order: array order, report values, manifest_hash and severity-gate exits are unchanged. Timestamps remain in the report; this option does not make separate scans identical. Without this flag, the existing object-key order is preserved. Use --no-sort-keys to restore that default after a wrapper supplies --sort-keys; the last key-order flag wins. This also restores the default order in nested objects.

Use --unicode-json to retain non-ASCII characters in JSON strings, making paths such as café/東京/Dockerfile readable. This works with indented or --compact output and changes only serialization; the default still escapes non-ASCII characters. Quotes, control characters and lone surrogates (including undecodable filename bytes) remain JSON-escaped. Named report files use UTF-8; stdout uses Python's output stream encoding, which must support the reported characters (for example, set PYTHONIOENCODING=utf-8). Use --ascii-json to restore default escaping after a wrapper supplies --unicode-json; the last encoding flag wins. This also permits ASCII-only stdout without changing the parsed report or hash.

Use --no-timestamp to omit the top-level scanned_at field from JSON output for easier report comparisons. Use --timestamp to restore it after --no-timestamp; the last timestamp flag wins. The timestamp remains present by default. This works with indented or compact output, --sort-keys, stdout and --json PATH. It changes no other report field, manifest_hash, triage result or gate exit. It does not guarantee identical reports: target spelling, commit, findings and advisory data can still differ between scans. Repeating the flag is harmless.

Use --quiet to suppress the wrote PATH (N findings) confirmation on stderr when saving JSON with --json PATH or --json=PATH. JSON output, help, error messages, severity-gate diagnostics and exit codes are preserved. With stdout output (including --json -), this flag has no effect on the report. Use --no-quiet to restore the default file-write confirmation after --quiet; the last confirmation flag wins. Neither flag changes JSON output or diagnostics.

Run python3 scan.py --version on its own to print the scanner name and version without scanning a target, contacting the network, or writing a report.

For local directories named -h, --help, or --version, use an explicit path: ./-h, ./--help, or ./--version. For example, python3 scan.py ./--help --no-osv scans the local --help directory offline. Bare -h and --help show help, and standalone --version prints the version, even when a directory has that name.

2. GitHub Action (composite; runs on the checked-out tree) — listed on the GitHub Marketplace as "Feldspar Discovery Scan":

- uses: actions/checkout@v4

• uses: project-feldspar-resources/feldspar-scan@v0.4.28 with: fail-on: high # none | low | medium | high | critical output: feldspar-scan.json triage: "true" # default; "false" = raw findings only

optional: keep the report

• uses: actions/upload-artifact@v4 if: always() with: { name: feldspar-scan, path: feldspar-scan.json }

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.28) 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):

curl -s -X POST -H 'Accept: application/json' \

-d 'url=https://github.com/owner/repo' https://project-feldspar.com/scan/scan

Human-readable form at https://project-feldspar.com/scan/; OpenAPI description at https://project-feldspar.com/openapi.json.

4. MCP server (for agents and IDEs; same hosted scan, same limits):

{ "mcpServers": { "feldspar-scan": { "type": "http", "url": "https://project-feldspar.com/mcp" } } }

Streamable-HTTP, stateless, no auth. Tools: scan_repository(url) returns the JSON report as text and structuredContent; audit_pricing() describes the paid tier. To keep answers small, scan_repository returns the most severe findings first, 25 unless max_findings asks for more (up to 200), and takes optional min_severity (critical/high/medium/low) and category (dependency-vuln/secret/config) filters. The summary counts always cover every finding; summary tables longer than 600 characters (per-file, per-package and per-advisory breakdowns) are left out and named under omitted. The web form and POST /scan/scan return the full report.

In Claude (claude.ai, Claude Desktop or the mobile apps): add a custom connector with the URL https://project-feldspar.com/mcp (no sign-in), then ask, for example, "Scan https://github.com/owner/repo with Feldspar Discovery Scan". The repository must be public on github.com, gitlab.com, codeberg.org or bitbucket.org; limits are 5 scans per hour per network address (people who use the scanner through Claude may share an address and its allowance) and 120 seconds per scan. Results are returned to Claude and not stored (privacy notice). Support: support@project-feldspar.com. 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 ye