Security model
A scanner should inspect your changes without trusting the code or configuration it is inspecting.
Scan the selected Git state, not whatever is on disk
Swarm treats repository content and analyzer output as untrusted input. It materializes the selected Git states into temporary snapshots, then runs managed analysis against those snapshots.
| Mode | Compared snapshots | Configuration and source excerpts |
|---|---|---|
| Ordinary local scan | Committed HEAD and the exact staged Git index | The staged index. Later unstaged edits do not replace scan input. |
scan --base <ref> | The unique merge-base commit and committed HEAD | Committed HEAD. Staged, unstaged, and untracked checkout files are not scan input. |
Base mode needs the comparison ref and common history already available locally. Swarm does not fetch Git history automatically. Missing ancestry or an unavailable comparison snapshot is an incomplete result, not evidence that the change is clean.
An intent-to-add file has no staged content to inspect. Staged Git LFS and submodule pointers cannot substitute for their underlying content. A binary path selected by an enabled source, formatting, or vulnerability check is reported as incomplete rather than silently treated as analyzed.
Prepare the Git history needed in CIUse managed analysis, not project commands
Swarm supplies its own data-only analyzer configuration and uses library APIs where available. Managed subprocesses receive explicit arguments without a shell. A scan does not run package-manager lifecycle scripts, project commands, or executable project analyzer configuration.
Repository .zedbeerc.jsonc settings are validated data. Swarm does not execute a project’s ESLint, Prettier, or Secretlint configuration. Only supported managed settings and rules can affect those checks.
These controls describe how Swarm invokes analysis; they are not a claim that its process runs in a separate virtual machine or operating-system sandbox. The installed scanner, managed analyzer dependencies, runtime, and host environment remain part of the trust boundary.
Installing packages or running your application elsewhere in CI is separate from a Swarm scan. Swarm’s scan behavior does not make those other workflow steps safe.
Configure supported checks without executable config- What it inspects
- When it runs
- How findings are attributed
- Which engine it uses
- What can be configured
- Important limitations
Keep snapshot content inside its boundary
Snapshot paths are validated beneath a Zedbee-owned temporary directory. Links are checked so repository content cannot redirect analysis outside the protected snapshot. Cleanup is attempted before the scan command returns, including after a failed scan.
If snapshot cleanup fails, Swarm marks the scan incomplete. It reports a remaining directory only when that directory’s identity can be safely validated. Otherwise, it asks the operator to inspect the operating system’s temporary directory without printing an untrusted path.
Resolve the reported permissions, locks, or filesystem problem before retrying. Repeated scans against the same unresolved problem can leave additional snapshots. Inspect any reported path before manually removing it.
Temporary JSON reports have a separate retention policy. They can remain after snapshot cleanup so a human or agent can read the full result.
Understand what remains on disknpx zedbee doctorA passing scan is not a security guarantee
Swarm evaluates enabled, applicable checks and attributes results to the selected changes. Its structural rules are local syntax patterns, not general interfile dataflow, taint, or reachability analysis. Secret detection does not audit all Git history, and vulnerability analysis depends on supported dependency inputs and the online OSV service.
An incomplete result means required analysis could not finish. Defaults keep these failures blocking, but configured exceptions can allow a scan with missing analysis to exit successfully. Review the full result as well as the exit code.
A clean result means no blockers were reported within the selected checks, inputs, and policy. It does not establish that the application has no vulnerabilities.
npx zedbee scan --format json --no-source > zedbee-report.json