[karthickmk2001]

Closes #66

What does this change, and why?

The runtime ingest API on secfoo serve, so live sensors (#67) and the CLI/CI (#80) can send and read evidence with the same API key the user already has. Contract and setup are in docs/REFERENCE.md → Runtime ingest API.

Endpoints (src/secfoo/runtime/api.py, versioned under /api/runtime/v1/, Authorization: Bearer <key>, project required):

• GET watchlist: the Build a vulnerable-function watchlist from advisories #52 watchlist, with an ETag (a hash of the entries, not generated_at). If-None-Match returns 304.
• POST events: an NDJSON batch, gzip allowed. It runs through Runtime evidence format, storage and secfoo runtime ingest #53's ingest_events, so a retried batch never double-counts. app / env query params (the sensor's SECFOO_APP / SECFOO_ENV) fill session lines that don't set them.
• POST heartbeat: {sensor_id, version, app, env, instances, dropped}. It registers the sensor in a new runtime_sensors table (for Runtime page: sensor health, live activity and alerts #72) and sums the drops.
• GET evidence: the runtime state of each open SCA finding (state, routes, coverage, conflict), reusing Runtime evidence in the SCA dashboard #57's sca_runtime.

Projects: matched on projects.identifier, exactly as runs are. An unknown project gets 404, with no auto-create, since evidence without a scan has nothing to attach to.

Keys:

• secfoo serve key create --name <label> [--project <p>] [--runtime-only], plus list and revoke. secfoo serve is now a command group, and plain secfoo serve [--host --port] works as before.
• Keys are stored only as SHA-256 (runtime_api_keys). The plaintext is printed once, to stdout, so KEY=$(...) captures it.
• A key can be limited to one project and/or to runtime endpoints only.
• Revoked keys get 401 immediately.
• The hosted portal implements the same contract separately, as the issue says.

Hardening:

• 5 MiB body / 20 MiB decompressed (gzip-bomb safe) / 50k lines per batch, and 120 requests per minute per key.
• Keys and payloads are never logged or echoed in errors.
• secfoo serve binds loopback by default. On any other --host, it refuses keys over plain HTTP unless --allow-insecure-runtime is set. The docs say how to put TLS in front.

Sensor side: secfoo/runtime/client.py load_sensor_config() reads:

• the key from SECFOO_API_KEY_FILE (or SECFOO_API_KEY);
• the server from SECFOO_SERVER, defaulting to secfoo cloud login's portal URL;
• SECFOO_PROJECT, SECFOO_APP and SECFOO_ENV.

There's no fallback account. It refuses non-HTTPS servers except loopback, and its repr never shows the key.

Note: the route and dependency are async on purpose. SQLite connections are bound to the thread that opened them, and FastAPI runs sync dependencies in a worker pool.

Testing

• pytest tests passes. 1183 passed locally. The only failures are the 4 existing Windows-only POSIX permission and symlink tests that fail on main too; Linux CI is unaffected.
• ruff check . adds no new findings.
• Added tests/test_runtime/test_runtime_api.py (24 tests), covering the issue's Done when:
  • a valid batch, and a replayed gzip batch that doesn't double-count
  • a key without access to the project, an unknown project that isn't created, and a revoked key
  • an oversized body, a gzip bomb, too many lines, and the rate limit
  • plain HTTP on a non-loopback bind, both refused and opted in
  • a watchlist ETag hit, and the heartbeat
  • the evidence endpoint
  • the sensor reading SECFOO_API_KEY_FILE / SECFOO_SERVER or the cloud-login default, and refusing incomplete config
  • keys stored hashed and never echoed
  • the serve key create/list/revoke commands

🤖 Generated with Claude Code

[github-actions]

Leaderboard update

• Closed Runtime ingest API: sensors use your Secfoo API key #66 (difficulty: hard): +10 points

karthickmk2001 now has 41 points (rank #1, Bronze). 9 more to reach Silver.

Full leaderboard