From d8a83f90fca9db07e2689327dbb3254b6bcd8776 Mon Sep 17 00:00:00 2001 From: Toni Bergholm Date: Sat, 18 Jul 2026 12:19:41 +0300 Subject: [PATCH] =?UTF-8?q?docs(security):=20Soon-tier=20process=20+=20inv?= =?UTF-8?q?entory=20docs=20(OSTIF=20T-11,=20T-14=E2=80=93T-21)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Executes the documentation half of the Soon tier from docs/audit/ostif-best-practices-audit.md: - T-16 (G-010/031/032): docs/security/vulnerability-response.md — internal handling steps, draft-advisory tracking, the boundary keeping private reports out of the public agent-triage pipeline, and a distinct-human- review rule for security fixes. - T-17 (G-011/030): docs/security/incident-response.md — five incident classes incl. the compromised/prompt-injected-agent class with its own contain/audit/revert playbook. - T-14 (G-012): docs/agents/ACCESS.md — access inventory with escrow-key custody first, then humans, then non-human principals (per-workflow GITHUB_TOKEN scopes, agent gh authority, dependabot). - T-18 (G-021): docs/security/data-handling.md — what is stored, what leaves the machine, and the no-true-delete / rotation-≠-erasure retention model stated plainly, incl. the PII/erasure tension. - T-19 (G-013/024): docs/security/subscriptions.md — automated feeds vs human subscriptions, with a confirm checkbox for the unverifiable half. - T-20 (G-025): docs/security/opsec-baseline.md — CI/account rules as standing policy; org-2FA enforcement recorded as PENDING maintainer action (deliberately not automated). - T-21 (G-016): docs/security/security.txt — RFC 9116 template for git-agentic.com/.well-known/ with yearly Expires. - T-11 (G-020/033): docs/security/third-party-inventory.md — both ecosystems, vendored/patched glib flagged first with its removal gate. - T-15 (G-022): CONTRIBUTING.md 'Security-review triggers' checklist (crypto/tlsio/transport changes, new deps, CI/permission changes, security fixes, first-release trigger). - SECURITY.md gains a pointer section to docs/security/. --- CONTRIBUTING.md | 27 +++++++ SECURITY.md | 12 +++ docs/agents/ACCESS.md | 39 +++++++++ docs/security/data-handling.md | 61 +++++++++++++++ docs/security/incident-response.md | 100 ++++++++++++++++++++++++ docs/security/opsec-baseline.md | 40 ++++++++++ docs/security/security.txt | 9 +++ docs/security/subscriptions.md | 37 +++++++++ docs/security/third-party-inventory.md | 65 +++++++++++++++ docs/security/vulnerability-response.md | 77 ++++++++++++++++++ 10 files changed, 467 insertions(+) create mode 100644 docs/agents/ACCESS.md create mode 100644 docs/security/data-handling.md create mode 100644 docs/security/incident-response.md create mode 100644 docs/security/opsec-baseline.md create mode 100644 docs/security/security.txt create mode 100644 docs/security/subscriptions.md create mode 100644 docs/security/third-party-inventory.md create mode 100644 docs/security/vulnerability-response.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8a0b41f7..8dec37a9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,6 +51,33 @@ CI runs `fmt --check`, `clippy -D warnings`, `cargo test --workspace`, and 5. **Keep the demos honest.** `sc demo` must still end by proving zero residue, and any new capability that warrants it gets a `demo/run_*.sh` proof. +## Security-review triggers + +Some changes get a security pass before merge as standing policy, not ad-hoc +judgment. If your PR does any of the following, say so in the PR description +and walk the checklist: + +- **Touches `crates/crypto`, `crates/tlsio`, or any transport/wire code** → + re-read the relevant [`docs/THREAT-MODEL.md`](docs/THREAT-MODEL.md) section; + state in the PR whether any documented boundary moves. If one does, the PR + must also update `THREAT-MODEL.md` (and add an ADR if the decision changes). +- **Adds or swaps a dependency (cargo or npm)** → the daily/PR advisory scans + must be green against it; add it to + [`docs/security/third-party-inventory.md`](docs/security/third-party-inventory.md) + in the same PR; vendored or patched copies additionally need a + `PROVENANCE.md` and an inventory annotation. +- **Adds a CI workflow, action, permission, or secret** → SHA-pin the action, + keep write permissions job-scoped, and update + [`docs/agents/ACCESS.md`](docs/agents/ACCESS.md) + (see [`docs/security/opsec-baseline.md`](docs/security/opsec-baseline.md)). +- **Is a security fix** → follow + [`docs/security/vulnerability-response.md`](docs/security/vulnerability-response.md): + tracked in a draft advisory, human review distinct from the author, no + public vulnerability detail before disclosure. +- **First release / publish channel (future)** → reopens the deferred audit + items (reproducible builds, SLSA provenance, published SBOM) — see + `docs/audit/ostif-best-practices-audit.md` §5, T-22…T-24. + ## Larger design changes The project records significant decisions as ADRs (`docs/adr/`, Nygard format: diff --git a/SECURITY.md b/SECURITY.md index df0a1f21..85546793 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -91,3 +91,15 @@ offered. Reports are credited in the disclosure and in release notes. Reports about the documented, deliberate boundaries above are welcome as hardening suggestions, but they are known limitations rather than vulnerabilities. + +## Internal process and further reading + +How reports are handled internally, how incidents are managed, and what the +project stores and can never delete are documented in +[`docs/security/`](docs/security/): [vulnerability +response](docs/security/vulnerability-response.md) · [incident +response](docs/security/incident-response.md) · [data handling & +retention](docs/security/data-handling.md) · [third-party +inventory](docs/security/third-party-inventory.md) · [opsec +baseline](docs/security/opsec-baseline.md). The access inventory lives at +[`docs/agents/ACCESS.md`](docs/agents/ACCESS.md). diff --git a/docs/agents/ACCESS.md b/docs/agents/ACCESS.md new file mode 100644 index 00000000..fe7b8075 --- /dev/null +++ b/docs/agents/ACCESS.md @@ -0,0 +1,39 @@ +# Access inventory + +Who — and what — holds which privilege over this project. One page, kept +current; [`incident-response.md`](../security/incident-response.md) depends on +it as the revocation checklist. Written as OSTIF-audit follow-up T-14 (G-012). + +## Cryptographic custody (most sensitive first) + +| Privilege | Holder | Notes | +|---|---|---| +| **Escrow keys** | Toni Bergholm | A standing decrypt privilege over every committed secret and protected path escrow-wrapped to them, and **every private branch before publish** (ADR-0044). Categorically more sensitive than repo-admin. Managed via `sc escrow`; rotation ≠ erasure. | +| `scl` identity/signing keys | Toni Bergholm | Kept **outside any working tree** (scanner footgun; a key committed under a private branch is sealed in). Sign commits (P22); compromise playbook: incident-response class 1. | + +## Humans + +| Privilege | Holder | Notes | +|---|---|---| +| GitHub org owner (`git-agentic`) | Toni Bergholm | Org 2FA requirement **not yet enforced** (pending — see [`opsec-baseline.md`](../security/opsec-baseline.md)). | +| Repo admin (`git-agentic/src-control`) | Toni Bergholm | Controls rulesets, security toggles, secrets. | +| `git-agentic.com` DNS/registrar | Toni Bergholm | Out-of-repo credential. | +| crates.io publish rights | — (N/A) | Workspace is `publish = false`; no crates.io tokens exist. Revisit at first release (audit T-24 trigger). | +| Security-report handler | Toni Bergholm | Per [`vulnerability-response.md`](../security/vulnerability-response.md). | + +## Non-human principals + +| Principal | Scope | Notes | +|---|---|---| +| `GITHUB_TOKEN` — `ci.yml` | `contents: read` | Ephemeral per-run. | +| `GITHUB_TOKEN` — `codeql.yml` | `contents: read` top-level; analyze job adds `security-events: write`, `actions: read` | Ephemeral per-run. | +| `GITHUB_TOKEN` — `audit.yml` | `contents: read`, `checks: write`, `issues: write` (job-scoped as of audit T-20) | Files RustSec findings as public issues. | +| `GITHUB_TOKEN` — `scorecard_analysis.yml` | `read-all` top-level; job adds `security-events: write`, `id-token: write` | Publishes Scorecard results. | +| AI agents (Claude Code et al.) | `gh` CLI under the maintainer's auth: issue/PR create, comment, label, close; local commit + push | Operate the public triage pipeline (`issue-tracker.md`). **Excluded** from draft security advisories and private reports; security fixes need distinct human review (see vulnerability-response.md). Compromise playbook: incident-response class 2. | +| Dependabot | Version + security update PRs (cargo, npm, github-actions) | PRs merge only through the standing required checks. | + +## Maintenance + +Update this file in the same PR as any change that grants, widens, or revokes a +privilege (new workflow permission, new maintainer, new publish channel, new +escrow recipient). diff --git a/docs/security/data-handling.md b/docs/security/data-handling.md new file mode 100644 index 00000000..61ce58af --- /dev/null +++ b/docs/security/data-handling.md @@ -0,0 +1,61 @@ +# Data handling and retention + +A plain statement of what data src-control stores, where it lives, what leaves +the machine, and — most importantly — what can never be truly deleted. Written +as OSTIF-audit follow-up T-18 (G-021); the underlying design boundaries live in +[`docs/THREAT-MODEL.md`](../THREAT-MODEL.md). + +## What the system stores + +src-control's purpose is storing user-supplied repository content, which by +design may include **sensitive data as a first-class feature**: committed +secrets (envelope-encrypted), protected-path file content (encrypted per +recipient set), private branches (fully sealed — content, paths, messages, DAG +shape), plus ordinary plaintext repository content, commit metadata (author +string, timestamps, messages), and sealed agent-session transcripts. + +The **project** (this repository and its maintainers) stores none of your data: +there is no telemetry, no phone-home, no hosted service. Every `.sc/` store +lives where you put it. Data leaves your machine only when *you* push/fetch to +a remote you chose, export to Git, or run `sc serve` for others. + +## The retention model — read this before committing sensitive data + +src-control is **content-addressed, append-only, and history-preserving**. +The consequences, stated plainly: + +- **There is no true delete.** Objects written into history persist; every + clone/fetch copies them. Removing a file at the tip does not remove it from + history. +- **Rotation and revocation are not erasure.** `sc secret rotate`, `sc grant` + revocation, and private-branch KEK rotation cut off *future* reads through + the current registry. Anyone who already held a key, a wrap, or a fetched + manifest keeps the ability to read what they already had. Real cutover of a + leaked credential always means rotating the **underlying external + credential** (the API key itself), not just src-control metadata. +- **Pre-P33 protected content stays equality-confirmable forever.** Content + sealed before randomized encryption (P33) used convergent encryption; an + observer of that ciphertext can forever confirm a guessed plaintext. +- **Escrow holders can read escrow-wrapped content** — including private + branches before publish. See [`docs/agents/ACCESS.md`](../agents/ACCESS.md). +- **Injected secrets are not isolated.** `sc run` places decrypted secrets in + a child-process environment: an authorized local context, observable by + same-user processes. + +## Personal data (PII) and erasure obligations + +Commit metadata (names, emails, timestamps) is personal data in most regimes, +and users can commit arbitrary PII as content. Because history cannot be +erased, **src-control cannot honor a right-to-erasure request for data already +committed and propagated** — the honest mitigations are: don't commit PII you +may need to erase; use protected paths/private branches so future revocation at +least limits *new* readers; and treat any committed-then-regretted PII like a +leaked credential (rotate/invalidate the real-world referent where possible). +Operators of `sc serve` instances that accept other people's pushes take on +data-controller-like responsibility for what they retain; the project provides +no compliance tooling for that today. + +## Current recommendation + +Unchanged from [`SECURITY.md`](../../SECURITY.md): pre-1.0 and pre-audit — do +not commit real production secrets yet. diff --git a/docs/security/incident-response.md b/docs/security/incident-response.md new file mode 100644 index 00000000..50076e9c --- /dev/null +++ b/docs/security/incident-response.md @@ -0,0 +1,100 @@ +# Security-incident response process + +What to do when the project itself — not its code — is attacked or compromised. +Distinct from [`vulnerability-response.md`](vulnerability-response.md), which +handles *reports about bugs*; this handles *incidents in progress or +discovered after the fact*. Written as OSTIF-audit follow-up T-17 +(G-011/G-030 — [`docs/audit/ostif-best-practices-audit.md`](../audit/ostif-best-practices-audit.md)). + +For every incident class: **contain first, investigate second, disclose +honestly third.** The access inventory in +[`docs/agents/ACCESS.md`](../agents/ACCESS.md) is the checklist of what can be +revoked; keep it current or this document degrades. + +## Incident classes and first moves + +### 1. Maintainer credential or signing-key compromise + +GitHub account, `git-agentic.com` DNS/registrar, or an `scl` identity/signing +key. + +- Rotate the compromised credential at its source (GitHub password + tokens + + sessions; registrar account; generate a fresh `scl` identity). +- Audit everything the credential could write since last-known-good: + `git log` on all branches, releases, repo settings, workflow files, ruleset + changes (`gh api .../rulesets`), org membership. +- For a compromised `scl` signing key: signatures bind identity to snapshot + ids — enumerate commits signed by the key after the compromise window, + re-sign or disavow them publicly. Remember **rotation ≠ erasure**: anything + the key could decrypt (secrets, protected paths, private branches it was a + recipient of) must be treated as read; rotate the underlying external + credentials, then `sc rewrap` at the tip. + +### 2. Compromised or prompt-injected agent (this project's distinctive class) + +AI agents operate this repository with real write authority (`gh` CLI issue/PR +operations, commits — see `docs/agents/`). A manipulated agent — via a crafted +issue body, poisoned dependency docs, or a compromised upstream skill — is an +incident, not a code bug. + +- **Contain:** revoke the agent's credential/session (the token it runs `gh` + with); stop any running agent sessions. +- **Audit:** review every agent-authored commit, PR, issue action, and label + change since last-known-good. Agent-authored security-relevant changes merged + without distinct human review are presumed tainted until re-reviewed. +- **Revert** anything harmful; force-push is blocked on `main` by ruleset, so + revert forward with explicit commits. +- **Find the injection source:** the issue/comment/document the agent ingested. + Remove it, and record the pattern — it is the signature to screen future + agent inputs against. +- **Disclose** in the repo (issue or advisory, depending on impact) — an + agent-authored malicious commit that shipped to users is a supply-chain + incident (class 4). + +### 3. Development/CI infrastructure compromise + +A compromised GitHub Action (repointed tag), a malicious dependabot PR merged, +CI secrets exfiltration. + +- Actions are SHA-pinned (audit T-2) precisely to narrow this: verify the pins + in `.github/workflows/*.yml` against upstream, and check the Actions run log + for the compromise window. +- `GITHUB_TOKEN` is ephemeral per-run; the blast radius is what its per-workflow + permissions allowed in tainted runs (see ACCESS.md). Check issues, checks, + and security-events written during the window. +- Rotate any non-ephemeral secret that was ever exposed to a tainted run + (currently: none configured beyond `GITHUB_TOKEN` — keep it that way). + +### 4. Supply-chain incident (dependency backdoored, or we shipped bad code) + +- **Inbound** (a dependency we use is announced backdoored): identify exposure + window from `Cargo.lock`/`package-lock.json` history; both lockfiles are + committed, so `git log -p` on them dates exactly when the bad version + entered and left. Assume CI and any local builds in the window are tainted; + see class 3. +- **Outbound** (we shipped it onward): nothing is published to crates.io or as + binaries today (`publish = false`), so the outbound surface is people + building from git. Disclose prominently (README banner + advisory), identify + the bad commit range, and provide a known-good commit to reset to. + +### 5. Data breach (user-entrusted content exposed) + +The system's design bounds this: secrets and protected content are ciphertext +to non-recipients, but **escrow holders and recipients can read what they hold, +and nothing already fetched can be un-fetched** (rotation ≠ erasure). If a +recipient/escrow key is exposed: treat every secret/protected file/private +branch it could read as disclosed; rotate the *underlying* external +credentials (API keys etc.), then rotate src-control-side keys and `sc rewrap`. +Notify affected users plainly about what was readable and for how long. + +## Every incident, after containment + +1. Timeline: what happened, when detected, window of exposure, what was + audited, what was rotated/reverted. +2. Disclose to affected parties (users, downstream projects) before or with + any public write-up; if operating law requires reporting, that is the + maintainer's jurisdiction-specific call (currently undocumented — audit + G-026). +3. Post-incident: what guardrail would have prevented or shortened it; file it + as an issue; update this document and `THREAT-MODEL.md` if a boundary + changed. diff --git a/docs/security/opsec-baseline.md b/docs/security/opsec-baseline.md new file mode 100644 index 00000000..2bc4abeb --- /dev/null +++ b/docs/security/opsec-baseline.md @@ -0,0 +1,40 @@ +# Operational-security baseline + +The standing rules for this project's development and CI infrastructure, so +they survive as policy rather than habit. Written as OSTIF-audit follow-up +T-20 (G-025). + +## CI + +- **GitHub-hosted ephemeral runners only.** No self-hosted runners — adding one + creates a persistent trust boundary this project has deliberately avoided. +- **`GITHUB_TOKEN` is the only CI credential.** No long-lived cloud keys, PATs, + or deploy tokens in Actions secrets. Any new secret needs a written + justification in [`docs/agents/ACCESS.md`](../agents/ACCESS.md) first. +- **Least-privilege, job-scoped permissions.** Workflow-level `permissions:` + stays read-only (`contents: read` / `read-all`); write scopes are granted + per job, only where used (audit T-20 scoped `audit.yml`'s + `checks: write` + `issues: write` to the job level). +- **Third-party actions are SHA-pinned** with a version comment; Dependabot + maintains the pins (audit T-2). New actions enter SHA-pinned or not at all. +- **Merges to `main` are ruleset-gated**: PR required, four required status + checks, up-to-date branch, no force-push/deletion, no bypass actors. + +## Accounts and devices + +- **Org 2FA requirement: PENDING.** `two_factor_requirement_enabled` is + currently `false` on the `git-agentic` org. Maintainer action: enable it in + org settings (Settings → Authentication security) after confirming the owner + account has 2FA. ☐ done as of ____. (An automated attempt was intentionally + not forced through — org-wide auth policy is a human call.) +- Maintainer GitHub account uses 2FA and per-device SSH keys; identity/signing + keys for `scl` live outside any working tree (see ACCESS.md). +- Development machines: full-disk encryption and OS auto-update expected; no + further device policy is codified for a solo project (revisit at second + maintainer). + +## Repository security features (all enabled 2026-07-18, audit Now-tier) + +Secret scanning + push protection, Dependabot alerts + security updates, +private vulnerability reporting, CodeQL (3 languages), Scorecard (weekly). +Disabling any of these is a policy change: PR + note here, not a quiet toggle. diff --git a/docs/security/security.txt b/docs/security/security.txt new file mode 100644 index 00000000..6892a0ff --- /dev/null +++ b/docs/security/security.txt @@ -0,0 +1,9 @@ +# RFC 9116 security.txt — deploy to https://git-agentic.com/.well-known/security.txt +# (website is hosted outside this repository; keep this template and the live +# file in sync — OSTIF-audit T-21/G-016. Refresh Expires at least yearly.) +Contact: mailto:toni@git-agentic.com +Contact: https://github.com/git-agentic/src-control/security/advisories/new +Expires: 2027-07-18T00:00:00.000Z +Policy: https://github.com/git-agentic/src-control/blob/main/SECURITY.md +Preferred-Languages: en, fi +Canonical: https://git-agentic.com/.well-known/security.txt diff --git a/docs/security/subscriptions.md b/docs/security/subscriptions.md new file mode 100644 index 00000000..0f893b1a --- /dev/null +++ b/docs/security/subscriptions.md @@ -0,0 +1,37 @@ +# Security-announcement subscriptions + +Who watches which advisory feeds, and what is automated vs. human-watched. +Written as OSTIF-audit follow-up T-19 (G-013/G-024). + +## Automated feeds (machine-checked, no human diligence required) + +| Feed | Mechanism | Cadence | +|---|---|---| +| RustSec advisories (cargo tree) | `rustsec/audit-check` in `audit.yml`, live DB fetch | Daily cron + every Cargo change | +| npm advisories (desktop tree) | `npm audit` in the `desktop` CI job + Dependabot alerts/security updates | Every PR + continuous | +| GitHub Advisory Database (all ecosystems) | Dependabot alerts + security updates (enabled 2026-07-18) | Continuous | +| CodeQL (rust, actions, javascript-typescript) | `codeql.yml` | Push/PR + weekly | +| OpenSSF Scorecard | `scorecard_analysis.yml` | Push + weekly | + +## Human subscriptions (maintainer: Toni Bergholm) + +The feeds a human should actually read, because they announce things scanners +only catch after a version is flagged: + +- **Rust security announcements** — `rustsec.org` feed and the Rust blog + security posts (toolchain CVEs are invisible to cargo-audit). +- **Tauri security advisories** (GHSA for `tauri-apps/*`) — covers both the + Rust crates and the JS bindings; the JS side has no RustSec coverage. +- **GitHub watch → security alerts** on this repository and on + direct-dependency repos of the crypto stack (RustCrypto orgs, rustls). +- **GitHub Changelog / Actions security announcements** — the CI supply chain + (this is how repointed-tag incidents get announced). + +Status: the maintainer should confirm these subscriptions are actually in place +— a repository cannot verify an inbox (audit G-024). Tick and date on +confirmation: ☐ confirmed as of ____. + +## Rule of thumb + +If a new dependency or ecosystem enters the project (first release channel, +new language, new platform), add its advisory feed here in the same PR. diff --git a/docs/security/third-party-inventory.md b/docs/security/third-party-inventory.md new file mode 100644 index 00000000..549d4bcc --- /dev/null +++ b/docs/security/third-party-inventory.md @@ -0,0 +1,65 @@ +# Third-party dependency and tool inventory + +The human-readable list of what this project is built from, spanning both +ecosystems. The machine-precise versions live in `Cargo.lock` and +`apps/desktop/package-lock.json` (both committed, integrity-hashed, and CI +verified); the CI-generated SBOM artifacts are the shareable form. Written as +OSTIF-audit follow-up T-11 (G-020/G-033). + +## ⚠️ Vendored, hand-patched dependency (read first) + +**`vendor/glib-0.18.5-patched/`** is an in-tree fork of the published +`glib 0.18.5` crate, wired in via `[patch.crates-io]` in the root `Cargo.toml`. +It carries a soundness backport for **RUSTSEC-2024-0429** ahead of the GTK3 +stack it belongs to. Consequences: + +- `Cargo.lock` records plain `glib 0.18.5` — any version-keyed scanner or SBOM + will misreport it (as vulnerable, or as clean upstream) unless annotated. + Scorecard's OSV check does exactly this (audit G-033/G-035; alert dismissed + with rationale). +- Provenance, patch content, and removal condition are documented in + `vendor/glib-0.18.5-patched/PROVENANCE.md`. Removal gate: Tauri 3 moving the + Linux stack to GTK4. + +## Rust workspace — direct dependencies by crate + +Architectural quarantine rules (which crate may use what) are in +[`CLAUDE.md`](../../CLAUDE.md); this is the inventory view. + +| Crate | Direct third-party deps | Role | +|---|---|---| +| `scl-core` | blake3, hex, thiserror, zstd | Content addressing, object model | +| `scl-vfs` | thiserror | In-RAM worktrees | +| `scl-gitio` | gix, anyhow, thiserror | Git interop (gix quarantined here) | +| `scl-crypto` | chacha20poly1305, x25519-dalek, ed25519-dalek, sha2, hkdf, rand_core, rand_chacha, zeroize, blake3, hex, thiserror | All cryptography (RustCrypto quarantined here) | +| `scl-repo` | blake3, hex, libc, regex, serde, thiserror, toml | Persistent store, merge, transports, policy | +| `scl-tlsio` | rustls, rcgen, ring, rustls-pki-types, hex, thiserror | TLS (quarantined leaf) | +| `scl-cli` | clap, anyhow, serde, serde_json, toml, hex | The `sc` binary | +| `scl-desktop` | tauri, tauri-build, tauri-plugin-dialog, serde, serde_json, toml | Desktop backend (read-only adapter) | + +Transitive tree: ~`Cargo.lock` (includes the Tauri/GTK3 Linux stack, source of +most accepted advisories in `audit.yml`'s documented ignore list). + +## Desktop frontend (npm, `apps/desktop`) — direct dependencies + +| Package | Kind | Notes | +|---|---|---| +| react, react-dom (19.x) | runtime | Renderer | +| @tauri-apps/api | runtime | IPC bindings to the Tauri backend | +| @pierre/diffs, @pierre/trees | runtime | Diff/tree rendering of repository content. **Watch items**: small-publisher, `@pierre/trees` is a pre-release pin (`1.0.0-beta.5`) — in the untrusted-content render path (audit G-006 note) | +| typescript, vite, vitest, @vitejs/plugin-react, jsdom, @testing-library/*, @types/*, @tauri-apps/cli | dev | Build/test toolchain | + +## Tools and services + +| Tool | Where | Purpose | +|---|---|---| +| GitHub Actions (SHA-pinned: actions/checkout, dtolnay/rust-toolchain, Swatinem/rust-cache, rustsec/audit-check, github/codeql-action, ossf/scorecard-action, actions/setup-node, actions/upload-artifact) | `.github/workflows/` | CI, advisory audit, CodeQL, Scorecard | +| Dependabot | `.github/dependabot.yml` | Version + security updates: cargo, npm, github-actions | +| system `git` / `ssh` | runtime (P12/P18) | Spawned for ssh transport and hosted-Git bridge (`SC_SSH`/`SC_GIT` override) | +| Rust toolchain 1.96.1 | `rust-toolchain.toml` | Pinned; bumped deliberately | + +## Maintenance + +Update this file in the same PR that adds/removes a direct dependency, a +vendored copy, a CI action, or a tool. Transitive churn is Dependabot's job, +not this file's. diff --git a/docs/security/vulnerability-response.md b/docs/security/vulnerability-response.md new file mode 100644 index 00000000..7fd16bfd --- /dev/null +++ b/docs/security/vulnerability-response.md @@ -0,0 +1,77 @@ +# Internal vulnerability-response process + +What the maintainer actually does when a report arrives through a +[`SECURITY.md`](../../SECURITY.md) channel (email to `toni@git-agentic.com` or +GitHub private vulnerability reporting). The public policy tells reporters what +to expect; this document is the internal side of those commitments. Written as +OSTIF-audit follow-up T-16 (G-010/G-031/G-032 — +[`docs/audit/ostif-best-practices-audit.md`](../audit/ostif-best-practices-audit.md)). + +## Roles + +- **Handler:** the maintainer (currently Toni Bergholm, `toni@git-agentic.com`) + owns every step below — acknowledgment, triage, fix, disclosure. When a second + maintainer exists, name a primary and a backup here. + +## The pipeline boundary (agents and public triage) + +This repository's default triage is **automated and public**: agents operate the +public GitHub issue tracker (`docs/agents/issue-tracker.md`), and the audit +workflow auto-files findings as public issues. Security reports are the one +class of work that must never enter that pipeline: + +1. **A privately received report is never filed, labeled, commented on, or + otherwise processed through public GitHub issues** until the fix has shipped + and the coordinated-disclosure date has passed. Tracking before then happens + in a GitHub **draft security advisory** on this repository (private, + access-controlled), which is the system of record for the report. +2. **An agent triaging public issues that encounters content resembling an + undisclosed vulnerability** (a crasher with security impact, a + confidentiality break, a report that should have been private) must stop, + apply no labels, post no analysis, and escalate to the handler privately. +3. Agents are not given access to draft advisories or the private report + channel. Remediation work an agent performs for a security fix is scoped to + the fix branch and must not restate the vulnerability details in public + commit messages, PR bodies, or issues before disclosure. + +## Review requirement for security fixes + +A security-fix PR requires **a human review distinct from the author** before +merge, regardless of who or what authored it. Agent-authored security fixes are +never merged on the strength of another agent's approval (audit G-032). For +other (non-security) changes the standing CI gates apply; this stricter rule is +scoped to security fixes until a second reviewing principal exists to enforce +it repo-wide. + +## Steps on receipt + +1. **Acknowledge** within 3 business days (the SECURITY.md commitment), from the + handler, confirming receipt and the expected next update. +2. **Record** the report as a draft security advisory (not a public issue): + report text, reporter contact and credit preference, affected commit, + initial severity guess. +3. **Triage** within 7 business days: reproduce (ask for the PoC if missing), + assess impact against [`docs/THREAT-MODEL.md`](../THREAT-MODEL.md) — a + documented deliberate boundary is out of scope as a vulnerability (tell the + reporter which boundary and why; welcome it as a hardening suggestion), a + real break gets a severity and priority. Communicate the verdict to the + reporter. +4. **Plan remediation** in the advisory: fix approach, target timeline within + the 90-day disclosure window, whether history/ciphertext already written is + affected (rotation ≠ erasure — state plainly what a fix does and does not + retroactively protect). +5. **Coordinate outward** if the vulnerability affects third parties (e.g. a + protocol break affecting anyone running `sc serve`, or an upstream + dependency issue): notify affected projects before public disclosure. +6. **Fix and verify with the reporter**: land the fix through a PR meeting the + review requirement above; ask the reporter to confirm the fix against their + PoC before closing. +7. **Disclose**: publish the advisory at the agreed date (default ≤ 90 days + from acceptance), credit the reporter unless they declined, note the fixed + commit/version, and add any new deliberate boundary to `THREAT-MODEL.md`. + +## After disclosure + +- Backport policy: pre-1.0, only `main` is fixed (per SECURITY.md). +- If the report revealed a process failure (not just a code bug), run the + relevant section of [`incident-response.md`](incident-response.md).