<div align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/eeco_logo_dark.png">
    <img src="assets/eeco_logo_light.png" alt="eeco" width="280">
  </picture>

<h1>Security</h1>

<p><i>eeco's safety model, and how to report a vulnerability.</i></p>

<p>
    <a href="README.md"><b>README</b></a> ·
    <a href="VISION.md"><b>Vision</b></a> ·
    <a href="docs/COCKPIT.md"><b>Cockpit</b></a> ·
    <a href="docs/USAGE.md"><b>Usage</b></a> ·
    <a href="docs/ARCHITECTURE.md"><b>Architecture</b></a> ·
    <a href="docs/PUBLIC_API.md"><b>Public API</b></a> ·
    <a href="EXTENDING.md"><b>Extending</b></a> ·
    <a href="CONTRIBUTING.md"><b>Contributing</b></a> ·
    <a href="docs/UPGRADING.md"><b>Upgrading</b></a> ·
    <a href="VERSIONING.md"><b>Versioning</b></a> ·
    <a href="CHANGELOG.md"><b>Changelog</b></a> ·
    <b>Security</b>
  </p>

</div>

---

eeco is a developer tool that runs inside a target repository. Its
safety model is documented in [`README.md`](README.md),
[`docs/USAGE.md`](docs/USAGE.md), and the architecture overview in
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). This file describes
how to report a vulnerability and the safety guarantees the project
considers in scope.

## Supported versions

Only the latest `v0.x` release receives security fixes; the pre-stability
line carries no support guarantee — see [`VERSIONING.md`](VERSIONING.md)
§2.1 and §8.1.

## Reporting a vulnerability

Use **GitHub Private Vulnerability Reporting** on this repository:

1. Go to <https://github.com/ajhahnde/eeco/security>.
2. Click **Report a vulnerability**.
3. Fill in the form. The report is private until disclosed.

Please include:

- The eeco version (`eeco version`) and your platform.
- A minimal reproduction or proof of concept.
- The expected vs observed behaviour and the impact you assess.

Acknowledgement is best-effort; eeco is maintained by a single
operator. A fix targets the next tagged release; a coordinated
disclosure timeline is negotiable on the advisory thread.

Please do not file a public issue for a security vulnerability.

## Safety guarantees in scope

These are the security-relevant invariants the project commits to.
A defect in any of them is a security report:

- **Write-scope.** eeco writes only inside the repo's gitignored
  workspace (default `.eeco/`). A path guard refuses `..` traversal
  and rejects any write target outside the workspace.
- **No auto-commit, no auto-push.** eeco never invokes `git commit`,
  `git push`, or any other write-side git command on the user's
  behalf, including on tracked-tree edits.
- **AI gating.** Every AI provider call passes through a single Gate
  that enforces explicit consent (`--ai` or `automation=auto`) and a
  per-invocation budget cap. A skip, over-budget, or provider error
  parks the prompt under `<workspace>/state/parked/` and queues a
  review item — there is no silent spend and no hard failure that
  loses the prompt.
- **Reversible hooks.** The only two touches outside the workspace
  are opt-in and reversible: a local `.git/hooks/pre-commit`
  (installed only when no hook exists; removed only on byte-identical
  match) and one namespaced entry in the AI CLI's user-global
  settings file (atomic edit, workspace-side backup, validate, restore
  on parse failure). Both are recorded in `state/hooks.json` so they
  can be cleanly undone.
- **`leak-guard`.** The `leak-guard` builtin workflow blocks a commit
  that would leak an AI-attribution string, a `Co-Authored-By`
  trailer, or a workspace engine path into a tracked file. The
  pre-commit hook (when enabled) refuses the commit; CI runs the
  same gate on every PR and `main` push.
- **Trust artefacts.** Each release tag carries a cosign-signed
  `SHA256SUMS` (keyless OIDC identity = the release workflow itself)
  and GitHub build provenance on every archive. The verification
  commands are in [`docs/USAGE.md`](docs/USAGE.md) §1.1.

## Out of scope

- A defect in a user's own scaffolded workflow script. The scaffold
  enforces the contract; the script's contents are the user's code.
- A defect in a third-party AI CLI selected by the operator via
  `ai_command`. eeco gates the call but does not audit the provider.
- A misconfiguration of `session_settings_path` that points outside
  the user's own settings file. eeco refuses a relative path and
  refuses to write a non-JSON file, but the destination itself is
  operator-chosen.
- Cosmetic findings in copy that do not affect safety
  (typos, link rot in docs, formatting).

## Telemetry

eeco emits no telemetry, ever. There is no analytics endpoint, no
crash reporter, and no opt-out switch because there is nothing to opt
out of. Network access is limited to the explicit AI provider call
(when consented and budgeted) and the read-only
`git ls-remote --tags` performed by `eeco update`.

---

[← Prev: Changelog](CHANGELOG.md)