Features

Documentation home · Previous: Quickstart · Next: Configuration

Software composition analysis

SBOM generation. Synapse produces a software bill of materials with owned per-ecosystem lockfile parsers and a pluggable producer, so detection is not tied to a single vendor. The owned producer (ownsbom) is the shipped default, emitting dependency-graph edges and requiring no third-party scanner binary; Syft is retained as an opt-in cross-check (SYNAPSE_SBOM_PRODUCER=syft). Current coverage: Go, npm, Yarn, pnpm, PyPI, Poetry, Pipfile, uv, Cargo, Maven, Gradle, RubyGems, Composer, NuGet, Swift, Dart, Hex/Elixir, Conda, R (renv), Julia, and Conan. It can also ingest a client-supplied CycloneDX SBOM as the scan inventory.

Multi-source detection. The primary source is Synapse's own advisory store, matched alongside a live advisory API; an offline third-party database is an opt-in cross-check rather than a dependency. Results are cross-correlated and de-duplicated, and each finding records the source and database version as evidence. Dropping the third-party database does not quietly lower OS-package recall: a scan whose OS-package distro the owned store does not cover is marked not-confident rather than reported clean. The owned store ingests OSV, GHSA, CSAF, and Ubuntu, Debian, Oracle Linux, AlmaLinux, openSUSE, and SUSE Linux Enterprise OVAL feeds plus Amazon Linux and Fedora updateinfo, Rocky Linux Apollo OSV, and apk secdb (Alpine, Wolfi, Chainguard) so that detection does not depend on one provider. A freshness check warns when a dated database is stale, and a precise detection mode routes single-source, uncorroborated findings into a needs-verify queue instead of failing the build on them.

Risk-based prioritization. Findings are ordered by exploitability: the known-exploited catalog first, then the exploit-prediction score, then CVSS. Ordering never uses raw CVSS alone, so what is actually being exploited rises to the top.

Reachability. A deterministic call-graph engine decides whether a vulnerable symbol is reachable from application code. A finding on code that is never called can be de-prioritized, and a deterministic proof supersedes any model opinion.

SBOM quality scoring. Beyond coverage, Synapse scores the SBOM document itself against the NTIA minimum elements and a set of semantic checks, then projects that onto named compliance profiles: NTIA 2021 and 2025, BSI TR-03183-2, and OWASP SCVS levels 1 and 2. The score is advisory and never gates a build, but it tells you whether the bill of materials is fit for downstream vulnerability lookup and sharing.

Scan cache. An optional cache, addressed by source content plus the producer version, skips re-cataloging an unchanged tree. A producer upgrade invalidates it automatically, so a stale catalog is never served. The cache directory must be operator-owned.

Secret and configuration scanning

Secret scanning. A read-only scan of the workspace flags hardcoded credentials using keyword prefilters, per-rule regular expressions, and a Shannon-entropy gate for generic secrets. Every match is redacted before it is stored, so the raw secret never reaches a log, the evidence ledger, or a report.

Misconfiguration and IaC scanning. Owned checks over parsed Dockerfiles, Kubernetes manifests, Helm charts, Kustomize overlays, Docker Compose, GitHub Actions workflows, Terraform (HCL), CloudFormation, and Azure Resource Manager and Bicep templates flag issues such as running as root, unpinned base images, pipe-to-shell installs, privileged or host-namespace pods, host-path mounts, dangerous capabilities, public storage, and open network rules. The rules are precision-biased: a dynamic or templated value is treated as unknown, so only an explicit unsafe literal is flagged.

Container image and OS-package analysis

When container image scanning is enabled, Synapse materializes the image root filesystem and runs owned catalogers over it, so a shipped artifact is inventoried even without a lockfile:

• OS packages. dpkg (/var/lib/dpkg/status) and apk (/lib/apk/db/installed) for Debian, Ubuntu, and Alpine, plus rpm from all three database backends: sqlite (rpmdb.sqlite, modern RHEL/Fedora/AlmaLinux/Rocky/Oracle), BerkeleyDB (Packages, RHEL 8 and Amazon Linux 2), and ndb (Packages.db, openSUSE and SLE), each parsed by owned pure-Go code so CGO_ENABLED=0 still builds. Packages are emitted with a distro qualifier so the advisory matcher keys them to the right OS ecosystem. CentOS Linux 7 is keyed to the RHEL 7 ecosystem as a documented approximation (it is a downstream rebuild of RHEL 7, and there was never a CentOS Stream 7), and reported as coverage=approximate; CentOS Stream and CentOS 8 or later stay coverage=unsupported (VERSION_ID=8 is ambiguous and Stream runs ahead of RHEL), never aliased to RHEL.
• Installed binaries. Go build information embedded in ELF, PE, and Mach-O binaries, and Python dist-info and egg-info metadata, become pkg:golang and pkg:pypi components.
• Image config hardening. An owned check over the image config and build history flags a container that runs as root (no USER, or an explicit root/uid-0), a credential baked into an environment variable, and a sensitive build command (a remote script piped to a shell, or an ADD of a remote URL). It reads only the recovered config, so it needs no filesystem walk, and a recognized credential in an env value is redacted before it reaches persisted scan data.

Every parser treats the image as untrusted input: reads are bounded, cancellable, and hardened against a hostile filesystem or a crafted package database.

First-party SAST and code quality

Synapse ships its own source-code analysis, not just dependency scanning. Two distinct engines, with distinct guarantees, so it is worth being precise about what each does.

The first-party SAST engine is a pattern scanner for dangerous idioms: a deterministic rule set over single lines with a bounded ten-line look-back, across many languages. It is good, and fast, at the class of bug that is visible in one place: a weak hash, a hardcoded credential, a shell command built by string concatenation, an unsafe deserializer. It is not an interprocedural or cross-file dataflow analyzer, and does not reason about framework routing, aliasing, or sanitizers, so it does not claim parity with a dataflow product. Its precision is pinned to a labelled corpus by the TestLabelledCorpusPrecisionAndRecall gate. Confirmed hits emit Kind=sast findings.

The stronger asset is the reachability engine: a taint and call-graph analysis over the sandboxed go/ssa and tree-sitter graphs (taintcallgraph, ssacallgraph, jvmreach, pyreach, srcreach). A finding it proves reachable is worth more than a larger pile of unproven ones, and a statically-proven hypothesis can be confirmed at runtime by a safe DAST probe (see below).

A SonarQube-style code-quality surface adds quality rules, quality gates and quality profiles, and hotspots. Third-party results enter the same governance path through SARIF ingest, so findings from other scanners are de-duplicated, prioritized, and reported alongside first-party ones.

Offensive testing (red team)

Offensive capabilities are governed by a written offensive policy and a kill switch, and run only inside the hardened sandbox with server-side scope and authorization:

• Recon enumerates a target's surface within the authorized scope.
• An attack-path graph correlates the asset inventory into reachable exposure chains.
• Chained exploitation advances step by step, each step admitted through the engagement's rules of engagement, producing its own sealed proof, and verified by a distinct verifier before the chain advances; a running chain is haltable by the kill switch. It runs as a governed no-host rehearsal (simulation) by default, reachable at POST /engagements/{id}/exploitation/rehearsals; a real host executor is a deliberate, review-gated extension point. The rehearsal route and the offensive kill switch are wired when the fleet transport is enabled.
• Adversary emulation runs benign technique variants that declare the detection each technique should produce, the offensive half of the purple-team ledger.

Runtime defense (blue team)

A distributed agent fleet extends Synapse from point-in-time analysis to runtime, over both host and Kubernetes estates:

• Agents collect host inventory (facts and installed OS packages, correlated with advisories into per-host CVE findings) and Kubernetes workload/exposure/identity inventory, with certificate enrolment, signed packaging and updates, per-asset coverage and freshness, and fenced leadership so scheduled work runs once.
• An eBPF detection engine observes process, file, network, and privilege events and evaluates a first-party detection catalog. A detection is evidence, not an alert: it is attributable, sealed into the same hash-chained evidence chain, and joined to the same asset and finding the static pillars reason about.
• A columnar telemetry tier retains raw events with a retention/cost model for retro-hunting.
• Governed response actions (isolate host, quarantine file, stop process) run under the same admission model as exploitation: server-side authorization, a human-approved sealed evidence record, argv-only execution, a mandatory reversal, and a declared blast radius. The plan, apply, revert and list routes live under /api/v1/blueteam/response; the default executor records the full governed ledger without a host effect, and the kill switch cancels pending actions.
• Purple-team coverage measures which techniques would actually be detected by joining emulation-expected detections with what actually fired, and reports the gap as a first-class number.

Cloud posture (CSPM)

Read-only posture connectors for AWS, Azure, and GCP run behind a sandboxed helper. Credentials are resolved by vault reference and passed to the helper out-of-band over an inherited file descriptor (never in argv, env, or logs), every cloud operation is authorized server-side against the engagement scope before it runs, and the connectors issue describe/list/get calls only. Findings include IaC-declared-vs-live-state drift.

Governance: suppression, VEX, and compliance

These share one rule that fits a chain-of-custody tool: acceptance is retain-and-mark, never delete. An accepted finding is still reported, persisted, and evidence-sealed. Only the --fail-on gate is exempted, and the exemption itself is recorded.

• .synapseignore suppression. Accept a finding by id, with an optional expiry and reason. An expired rule re-surfaces the finding and trips the gate again.
• In-scan VEX. An in-repo OpenVEX document (.synapse.vex.json) marks a finding not_affected or fixed at scan time, on the same retain-and-mark surface.
• Compliance benchmark. Re-projects findings onto a control specification and reports per-control PASS or FAIL. It reads every finding, including accepted ones, so acceptance can never flip a control to PASS.

Data governance: hold, export, and erasure

The detection projection carries data about identifiable hosts and users, so it is governed separately from the findings and separately again from the evidence chain, which is permanent by design and never touched by any of this.

• Legal hold. Placing a hold on an engagement exempts its detection data from retention expiry and refuses on-demand deletion while the hold stands. Placing and releasing both demand a reason and are written to the append-only audit log, so preservation is attributable. Retention expiry and erasure both consult the hold and fail closed: a checker error blocks the deletion rather than allowing it.
• Subject-access export. A read-only bundle of what the control plane holds for one engagement, the detections plus any active holds. The export is itself an audited access, because a subject-access request is a governance event.
• On-demand erasure. Deletes an engagement's detection projection now, legal-hold-checked, audited with the actor and a required reason. It removes the queryable projection only; the hash-chained evidence is preserved, so erasure never breaks the chain that proves what was done.

Requires the fleet and its detection ingest, because the detection projection is the data being governed. The Data governance screen documents the flow.

License compliance

Declared licenses are resolved to SPDX ids, including full SPDX expressions with AND, OR, and WITH. A curated category and risk model classifies each license. Coordinate recovery identifies shaded or metadata-less JARs by their hash, so their licenses and vulnerabilities are attributed correctly rather than lost.

Findings and evidence

One finding per issue, de-duplicated and updated in place across re-scans. Every artifact is hash-chained into a tamper-evident custody record. A broken chain blocks the report. The audit log and evidence ledger are append-only and can be anchored with an RFC-3161 timestamp for external, tamper-proof proof.

Hardened execution

Heavy or capability-sensitive tools are shelled out to pinned binaries via argv arrays, never a shell string, so no target or agent input is ever concatenated into a command. On a Linux host they run inside a bubblewrap sandbox with seccomp, cgroup limits, and egress scoping. Scope and the authorization window are enforced server-side before any tool runs. If the sandbox is requested but unavailable, startup fails closed rather than running unsandboxed.

Access control

Per-action role-based access control and tenant isolation flow through a single authorization chokepoint. Roles cover admin, consultant, reviewer, and read-only, with separation of duties so a machine identity can never confirm its own claim. Secrets stay server-side in a credential vault with placeholder substitution.

Reporting and standards

Reports are templated from stored data and are deterministic. Compliance mapping from CWE to OWASP, PCI, and ISO controls comes from a curated, source-cited table, with no model in the path. Synapse exports CycloneDX and SPDX with PURL, SARIF, OpenVEX, and CSAF 2.0 VEX; it also ingests CSAF and OVAL advisory feeds and uses KEV plus EPSS for prioritization. The CSAF VEX export (GET /api/v1/engagements/{id}/export/csaf) describes the same publishable findings as OpenVEX; it is not a general-purpose CSAF advisory publisher. Import a client-supplied CycloneDX SBOM as the engagement inventory. Export the retained SBOM as CycloneDX 1.6 or SPDX 2.3 / 3.0 through the engagement API or dashboard export button. SPDX is export-only; it is not an accepted SBOM import format.

Bounded AI analysis (optional)

An optional analysis layer turns raw scanner and agent output into confirmed findings. It is deterministic-first and gated. The model only ever proposes. Every claim is a typed judgment with a lifecycle of propose, verify, confirm. Gated capabilities promote only on a distinct verifier's sealed verdict above the evidence threshold. Ungated ones need a human accept. The agent can never confirm its own claim, and no model ever sits in the report path.

False-positive triage keeps the opinion/authorization boundary explicit: a single model can mark a finding suspected_fp but cannot affect a gate. A distinct verifier must agree, then a deterministic policy keeps high/critical, secret, and dangerous-CWE findings in human review. The full typed decision and model/prompt/policy metadata are sealed into the scan evidence chain before an exemption can take effect. Without an evidence ledger the decision remains advisory-only. Secret findings are never sent to the LLM because even a redacted finding description cannot make its raw source context safe to transmit.

Capabilities include reachability proposals, pattern SAST, a taint engine over the call graph, threat modeling over an architecture seam, AI critique and risk narrative, and human-gated write-up drafts.

Deterministic reachability

Reachability is the strongest anti-hallucination signal: a deterministic proof supersedes any LLM opinion. The Go path builds a real call graph (Tier-2) and proves whether a vulnerable symbol is actually called. For Python (SYNAPSE_PYREACH_ENABLED), a source-only scanner proves whether a declared PyPI package is imported by first-party code at all, a declared-but-never-imported package (a dead dependency) becomes a deterministic Tier-1 not_reachable judgment that the OpenVEX export turns into a vulnerable_code_not_in_execute_path justification. It is honestly tiered (import-level, weaker than a call path) and conservative: a target that uses dynamic imports (importlib/__import__), a non-Python target, or an unresolvable import name yields no verdict rather than a false "not reachable" that could suppress a real vulnerability.

When SYNAPSE_PYREACH_TIER2_ENABLED=true, a CGO-enabled synapse-ast sidecar parses Python without importing or executing it, resolves imports, lexical call targets, constructors, receiver methods and conservative inheritance, then queries advisory-provided affected symbols. A reached symbol produces a bounded Tier-2 call path even when unrelated coverage is incomplete. A Tier-2 negative is emitted only when extraction, resolution and symbol placement are complete; otherwise the Tier-1 judgment remains. The Tier-2 flag is ignored unless SYNAPSE_PYREACH_ENABLED=true.

Python semantic taint

SYNAPSE_PYTAINT_ENABLED=true enables a separate source-only Python value-flow pass. The synapse-ast sidecar emits bounded value slots and expression/assignment/return flows; the analyzer then binds positional and keyword arguments, method receivers, parameters, and return values across the resolved call graph. It supports Flask, Django, and FastAPI request entrypoints and initial SQL, command, path, SSRF, XSS, deserialization, and redirect sink models. Sanitizers are class-specific: HTML escaping stops an XSS path but cannot hide the same value reaching os.system, and yaml.safe_load only neutralizes unsafe-deserialization semantics.

Every hit is a gated CapSAST proposal at score zero under system:python-taint-scan; this pass has no verification or self-confirmation path. The audit witness contains only bounded relative positions and closed catalog metadata, never source contents or literal values. Parser/resolution gaps are recorded as incomplete coverage: a real positive path may still be proposed, but absence of a path is never published as a clean judgment. Scan JSON exposes this distinction in analysis_coverage as complete, partial, unavailable, or not_applicable, with closed failure reasons, bounded counters, and an aggregated gap histogram. Partial/unavailable analysis also produces an operator-facing source_warnings entry; tool stderr, target paths, and source text are never copied into either surface.

After a distinct verifier confirms the proposal, its bounded source-to-sink position trace is retained on the finding. The sink becomes the finding's primary source location, and SARIF 2.1.0 exports the ordered trace as codeFlows/threadFlows, together with coverage-complete and graph-truncated properties. A trace contains at most 64 canonical repository-relative positions and never contains expressions, source lines, literal values, or internal value identifiers. The feature needs judgments plus a CGO-enabled synapse-ast; it does not import, execute, or compile target Python and therefore does not require the target-compilation sandbox.

JavaScript/TypeScript semantic taint

SYNAPSE_JSTAINT_ENABLED=true enables the source-only JavaScript/TypeScript value-flow pass in SCA scans. The sandboxable synapse-ast sidecar emits bounded facts for imports, lexical values, assignments, calls, returns, and coverage gaps; the analyzer follows value flow without installing dependencies or executing target code.

The reviewed catalog covers request-derived input and command/code, filesystem, SSRF, XSS, redirect, regular-expression, template, deserialization, XPath, and log-injection sinks. Each positive witness mints only a score-zero, gated CapSAST proposal under system:js-taint-scan; a distinct verifier must confirm it. Incomplete or unavailable analysis is surfaced as coverage/warnings and can never create a clean result. Bounded audit and SARIF traces contain positions and catalog metadata only, never source contents, literal values, or internal value identifiers. The feature requires judgments plus a CGO-enabled synapse-ast; because it is source-only, target-compilation sandboxing is not required.

Runtime confirmation (DAST)

A gated SAST hypothesis can be confirmed at runtime by a safe HTTP probe. When a distinct verifier's runtime probe confirms the hypothesis, the confirmed judgment is projected into a Kind=dast finding, the dynamically-proven twin of the Kind=sast projection (a statically or LLM-confirmed hypothesis stays Kind=sast). A DAST finding records reachability = reachable, because the probe demonstrated the sink is actually reachable and exploitable.

The runtime probe never runs unguarded. It executes only through the governed workflow, which requires, server-side: the target inside the engagement's authorization scope and window; the sandbox with kernel-enforced egress confinement (the probe is refused when the host cannot enforce the egress allowlist); and explicit HITL approval before any packet is sent. The verifier records only a structured, closed-token result (a proof class plus a rationale), raw probe output lives in sealed, hash-chained evidence, never in the model transcript. The agent can only propose the hypothesis; a distinct verifier confirms it, so a claim can never confirm itself.

Next: Configuration