Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
12 changes: 12 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
39 changes: 39 additions & 0 deletions docs/agents/ACCESS.md
Original file line number Diff line number Diff line change
@@ -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).
61 changes: 61 additions & 0 deletions docs/security/data-handling.md
Original file line number Diff line number Diff line change
@@ -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.
100 changes: 100 additions & 0 deletions docs/security/incident-response.md
Original file line number Diff line number Diff line change
@@ -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.
40 changes: 40 additions & 0 deletions docs/security/opsec-baseline.md
Original file line number Diff line number Diff line change
@@ -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.
9 changes: 9 additions & 0 deletions docs/security/security.txt
Original file line number Diff line number Diff line change
@@ -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
37 changes: 37 additions & 0 deletions docs/security/subscriptions.md
Original file line number Diff line number Diff line change
@@ -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.
Loading
Loading