diff --git a/sales/flight-recorder-pilot/01-offer.md b/sales/flight-recorder-pilot/01-offer.md new file mode 100644 index 0000000..803aa62 --- /dev/null +++ b/sales/flight-recorder-pilot/01-offer.md @@ -0,0 +1,92 @@ +# Agent Flight-Recorder Pilot + +**A fixed-price pilot that gives your team a verifiable record of what its coding +agents actually did. Once a session is sealed, your security reviewers and +auditors can check its record themselves, without trusting us or the tool that +produced it.** + +## The problem + +Your engineers already let Claude Code read files, run shell commands, and edit +code in real repositories. When someone asks "what did the agent do on that +change?", the answer today is a chat transcript or a log file on a laptop. Anyone +with access could have edited it, and nobody downstream can check it. + +Security questionnaires, enterprise customers, and internal risk owners are +starting to ask that question. "We trust the developer" is a weak answer. + +## What the pilot does + +In two to four weeks, on your machines and your repositories, we: + +1. **Record.** We install Korg's open-source capture hook for Claude Code in the + pilot repositories of a small group of developers. Every session becomes its + own ledger: prompts, model turns, tool calls, and tool results (long results are + truncated at 8,000 characters), causally linked and SHA-256 hash-chained. +2. **Redact before anything is written.** Recognized secrets (API keys, bearer + tokens, private keys, JWTs, credentialed URLs) are replaced before an event is + hashed or saved, and we prove it with a planted canary secret. +3. **Seal selected sessions.** For the changes that matter, we mint a signed + Certificate (`korgcert@v1`, Korg's file format, not a compliance certificate). + It embeds the session's events plus a summary of agents, tool counts, and file + paths used by file tools. The summary is re-derived from the events, so it + cannot disagree with the record. + Anyone can verify it offline with a command-line verifier (Rust, Python, or + Node.js) or a browser tab that uploads nothing. +4. **Prove tampering is caught.** We edit records, delete them, and re-sign them with + the wrong key in front of your team and show each verifier name the exact break. +5. **Gate CI** (Recorder + CI Gate and Evidence Pack). A GitHub Action verifies + Certificates against your pinned key on pull requests and fails the job on any + tampered or unverifiable file. +6. **Report.** You get a written findings report with coverage numbers, drill + results, measured overhead, gaps, and a recommendation on whether to roll out. + +## What you can do afterwards + +- Answer "what did the agent do in the session behind PR #1234?" with a record a + third party can verify, not a screenshot. +- Give security and GRC owners artifacts they can inspect themselves when they + assess change-management and logging controls for AI-assisted development. +- Decide on a rollout using your own measurements of coverage and overhead, + not vendor claims. + +## Why this is credible + +- **Open source, no lock-in.** Korg is MIT / Apache-2.0. The format + (`korg-ledger@v1`) is a public spec with three independent verifiers (Rust, + Python, JavaScript) that pass the same conformance vectors. You keep everything + we install. +- **It runs in your environment.** Capture, sealing, and verification all happen on + your machines. We run no hosted service, and nothing is sent to us unless you + choose to share it. +- **We disclose the limits.** Live capture is Claude Code only. A signature proves + a key, not a person. Until a session is sealed, its record can be rewritten by + whoever controls the machine, including the agent itself. A sealed Certificate + fixes it from that point on, and the pilot sets out who seals and when. The full + list is in [CLAIMS.md](CLAIMS.md#limits-to-disclose). + +## What this is not + +This is not a compliance certification, an audit, or legal advice. The pilot +produces evidence that you and your auditors may use. Whether that evidence meets +any control or regulatory requirement is your auditors' call. + +## Options + +| | Recorder | Recorder + CI Gate | Evidence Pack | +|---|---|---|---| +| Price | $6,500 | $14,500 | $24,000 | +| Duration | 2 weeks | 3 weeks | 4 weeks | +| Repositories / pilot developers | 1 / up to 5 | up to 2 / up to 10 | up to 3 / up to 20 | + +Fixed price, 50% at signature and 50% on acceptance against +[written criteria](09-acceptance-criteria.md). Full comparison: +[08-pricing.md](08-pricing.md). + +## Next step + +A 30-minute scoping call, then our [technical discovery questionnaire](05-discovery-questionnaire.md). +We confirm fit within two business days of receiving your answers. If Korg cannot +capture your agents, we will tell you then, before you pay anything. + +Contact: {{SELLER_NAME}} · {{SELLER_EMAIL}} diff --git a/sales/flight-recorder-pilot/02-ideal-customer-profile.md b/sales/flight-recorder-pilot/02-ideal-customer-profile.md new file mode 100644 index 0000000..5e9a969 --- /dev/null +++ b/sales/flight-recorder-pilot/02-ideal-customer-profile.md @@ -0,0 +1,78 @@ +# Ideal customer profile + +Use this to decide whether a prospect is worth a scoping call, and to disqualify +early when Korg cannot do what they need. + +## Primary profile + +**An engineering organization of 20–500 engineers that already uses Claude Code +on production repositories and has someone who must answer for what the agents +did.** + +| Attribute | Strong fit | Why it matters | +|---|---|---| +| Agent in use | Claude Code, used interactively or headless (`claude -p`), on macOS or Linux | It is the only live capture path ([L1](CLAIMS.md#limits-to-disclose), [L11](CLAIMS.md#limits-to-disclose)) | +| Code host / CI | GitHub and GitHub Actions | The CI gate is a GitHub composite action ([C13](CLAIMS.md#claims-you-may-make)) | +| Audit exposure | SOC 2 or ISO/IEC 27001 in place or in progress; enterprise customers sending security questionnaires; regulated industry (fintech, health tech, insurance, public-sector suppliers) | Someone owns the question "what did the agent change?" | +| Agent maturity | Past the experiment stage: agents edit code that ships, or a wider rollout is planned this quarter | The record matters only once the work is consequential | +| Buyer | A platform/DevEx lead, security engineering lead, or head of GRC with a budget line for AI tooling governance | They can sign a five-figure pilot without a procurement cycle | +| Engineering culture | Comfortable installing open-source CLI tools and reading a hash-chain spec | The pilot runs on their machines, not on our SaaS | + +## Buying triggers + +Look for one of these in the last 90 days: + +- A customer security questionnaire or RFP asked how AI coding assistants are + governed or logged. +- An audit window (SOC 2 Type II period, ISO surveillance audit) opens within six months + and AI-assisted change management is a new topic for the auditors. +- An incident or near miss involving an agent: an unexpected file edit, a + destructive command, a leaked secret in a transcript. +- Claude Code is moving from a few enthusiasts to a team-wide or company-wide + rollout. +- A public post, talk, or job listing that mentions AI governance, agent + observability, or "AI SDLC" controls. + +## Personas + +| Persona | What they care about | Lead with | +|---|---|---| +| **Platform / DevEx lead** | Rolling out agents without slowing developers or creating a security veto | A capture failure never fails a session; the hook's added time is measured in the pilot, not promised; nothing is hosted | +| **Security engineering lead** | Secret leakage, blast radius, "show me what it ran" | Redaction before hashing, canary drill, tamper drills, local-only trust boundary | +| **GRC / compliance owner** | Evidence for change-management and logging controls that an auditor will accept | Independently verifiable records; control-evidence mapping (Evidence Pack); no certification claims | +| **CTO / VP Engineering** | Customer trust, enterprise deals, avoiding a bad headline | A clear yes or no on rollout within a month, at a fixed price | + +## Secondary profile (qualify carefully) + +- **Teams mainly on OpenAI Codex CLI.** We offer only a feasibility replay of a + recorded trace ([L1](CLAIMS.md#limits-to-disclose)). Sell Recorder + CI Gate only + if they also have Claude Code users, or if a feasibility answer alone is worth the + price to them. +- **Agent-tool vendors and consultancies** that want to attach verifiable + Certificates to agent-produced deliverables for their own clients. Capture has + to run on Claude Code. + +## Disqualify (do not sell the pilot) + +- The team uses only GitHub Copilot, Cursor, Windsurf, Gemini CLI, or another + agent with no Korg adapter. +- They want a certificate of compliance, an audit opinion, or legal assurance. +- They need a hosted, multi-tenant dashboard, central log collection, SSO, or RBAC + now. These do not exist ([L8](CLAIMS.md#limits-to-disclose)). +- They need agent actions blocked or approved in real time. This pilot records + actions; it does not prevent them. +- The pilot developers are on Windows only ([L11](CLAIMS.md#limits-to-disclose)). +- Policy forbids installing Python packages or adding Claude Code hooks on + workstations, and they will not grant a pilot exception. +- They need a trusted timestamp, or proof that a named person (not a key) produced + a change ([L3, L4](CLAIMS.md#limits-to-disclose)). + +## Qualification checklist (first call) + +- [ ] Claude Code in use today on at least one production repository +- [ ] Pilot workstations are macOS or Linux +- [ ] GitHub and GitHub Actions (required for the CI Gate tiers only) +- [ ] A named owner for the agent-governance question +- [ ] A trigger from the list above, with a date +- [ ] Budget authority for the selected tier +- [ ] Agreement that the output is evidence, not certification diff --git a/sales/flight-recorder-pilot/03-scope-and-exclusions.md b/sales/flight-recorder-pilot/03-scope-and-exclusions.md new file mode 100644 index 0000000..c9ab2e5 --- /dev/null +++ b/sales/flight-recorder-pilot/03-scope-and-exclusions.md @@ -0,0 +1,140 @@ +# Scope and exclusions + +Attach this to the statement of work. Tier names, limits, and prices match +[README.md](README.md#pilot-at-a-glance). + +## In scope — all tiers + +1. **Install capture** for the agreed pilot developers on Claude Code (macOS or + Linux workstations): + - Install the `korg-ledger-py`, `claude-code-adapter`, and `korg-seal` Python packages + from a local checkout of the public Korg repository, at a pinned commit at or + after `781bc41`. Install them with `--no-deps`, plus `cryptography` from the + customer's usual index, so that pip never looks up the unregistered + `korg-ledger-py` name on PyPI ([L10](CLAIMS.md#limits-to-disclose)). + - Register the `korg-hook` capture hook (`PostToolUse`, `Stop`, `SubagentStop`) + **per pilot repository**, in that repository's `.claude/settings.local.json`. + Because the file is created by hand, it is added to `.gitignore` and + `git check-ignore` confirms it stays out of commits. We also check that + `~/.claude/settings.json` has no `korg-hook` entry from an earlier + `korg-setup` run, so only Claude Code sessions in pilot repositories are + recorded. The hook entries are reviewed with the developer before they are + written. `korg-setup` is not used ([L16, L17](CLAIMS.md#limits-to-disclose)). + - Ledgers are written to `~/.korg/sessions/.jsonl` on each + workstation. Custom locations are not used in the pilot, because not every + Korg command honors `KORG_HOME`. +2. **Backfill (optional).** With the developer's consent, convert existing Claude + Code session files for the pilot repositories only, with `korg-backfill + --projects-dir` pointed at each pilot repository's Claude Code project folder. +3. **Verification toolchain.** Set up verifiers from at least two independent + implementations ([which verifier checks what](CLAIMS.md#which-verifier-checks-what)): + - Python: `python -m korg_ledger lint` (ledgers) and `korg-seal verify` + (Certificates). + - JavaScript: `verify.mjs` from Node.js, or the browser pages for reviewers. + - Rust: `korg-verify`, built from source on at least one customer machine or CI + runner where a Rust toolchain is allowed. It lints a Certificate for secrets + directly (`--require-redacted`). Without Rust, the Python lint checks a + Certificate's extracted events instead + ([which verifier checks what](CLAIMS.md#which-verifier-checks-what)). + - Do not use the `@korgg/ledger-verify` npm package or the `korg-verify` crate + from crates.io. Both are stale 0.1.0 releases that predate Certificates and + redaction ([L10](CLAIMS.md#limits-to-disclose)). +4. **Issuer key setup.** The customer generates an Ed25519 issuer key with + `korg-seal` and records its public key as the pinned key. The customer also + chooses a sealing model ([06 §5](06-security-and-data-handling.md#5-keys)). +5. **Certificates.** Mint `korgcert@v1` Certificates for a sample of pilot + sessions chosen by the customer, only from ledgers that pass the redaction lint. +6. **Drills.** Run the tamper, redaction-canary, and wrong-key drills defined in + [09-acceptance-criteria.md](09-acceptance-criteria.md). +7. **Measurement.** Capture coverage (transcript tool calls compared with ledger + events), hook overhead, and the time between capture and sealing, on real pilot + sessions. +8. **Findings report and readout** following + [10-sample-report-outline.md](10-sample-report-outline.md). + +## Additional scope — Recorder + CI Gate + +9. **CI verification gate.** Add a workflow to the pilot repositories that runs the + `verify-korgcert` GitHub composite action, referenced by commit SHA and pinned + to the customer's issuer key, so that tampered or unverifiable Certificates + fail the job. Because the action does not check redaction, the workflow also runs + a redaction-lint step: `korg-verify --require-redacted` built in the job, or the + Python lint over each Certificate's extracted events. Because Certificates + contain full session content, the customer chooses where the CI job reads them + from: committed to the pilot repository after review, or fetched from a private + customer store. PR comments (which show the claim, tool counts, and file paths) + are on by default in the action, so the workflow sets `comment: "false"` unless + the customer turns them on. +10. **Public anchoring (opt-in).** If the customer agrees, commit a file that + contains **only** a Certificate's tip hash to a public GitHub repository, bind + it with `korg-seal anchor`, and show `korg-seal resolve`. The Certificate itself + is never published ([L15](CLAIMS.md#limits-to-disclose)). If the customer does + not opt in, deliver a memo that explains the structural-only option and what + it does not prove. +11. **Second-agent feasibility.** The customer records and sanitizes one + OpenAI Codex CLI WebSocket trace, following our sanitization checklist (the + capture includes authentication headers). We write a short replay script, + which the customer keeps, to run the trace through the `codex-ws` adapter into a + `korg-ledger@v1` journal. We verify that journal and report what production + capture of Codex would take. This is a feasibility finding, not a capture + deployment. + +## Additional scope — Evidence Pack + +12. **Control-evidence mapping workshop** (half day, remote). With the customer's + GRC owner, map pilot artifacts to the controls *the customer selects* from its + own framework, for example change-management and logging controls in SOC 2 or + ISO/IEC 27001. The output is a draft evidence matrix for the customer and its + auditor to review. It is not an audit opinion. +13. **Operating runbook.** Written procedures for rollout beyond the pilot group, + key custody and rotation, ledger retention, redaction incidents (using + `rechain-redacted`), and verifier upgrades. +14. **Executive readout** for a second audience, such as leadership or the audit + committee. + +## Exclusions — all tiers + +The following are out of scope. Any of them can be quoted separately through a +change order ([08-pricing.md](08-pricing.md#change-orders)). + +- **Certification or attestation.** No compliance certification, audit opinion, + legal advice, or statement that the customer meets any standard or regulation. +- **Agents with no live capture path.** Live capture of GitHub Copilot, Cursor, + Windsurf, Gemini CLI, Codex CLI, or any agent other than Claude Code. Codex + appears only as the feasibility replay in item 11. +- **Hosted or networked components.** No hosted service, central log server, or + shared dashboard. `korg-server` and `mcp_server.py` are not deployed on any + network ([L8](CLAIMS.md#limits-to-disclose)). +- **The `stream-json` adapter**, because its blob store is not redacted + ([L7](CLAIMS.md#limits-to-disclose)). +- **Prevention.** No blocking, approving, or sandboxing of agent actions. +- **Fleet rollout.** Endpoint-management packaging (MDM, Ansible, golden images) + and installs beyond the tier's developer limit. +- **Windows workstations** ([L11](CLAIMS.md#limits-to-disclose)). +- **DLP and data classification.** Redaction beyond `korg-redact@v1` rules; detection + of personal data or proprietary code inside ledgers. +- **Trusted timestamping, identity binding, and key registries** beyond the + pinned-key and git-tip mechanisms in [CLAIMS.md](CLAIMS.md). +- **Changes to Korg itself.** New adapters, features, or bug fixes. Bugs found + during the pilot are reported upstream through the public repository (security + issues through [SECURITY.md](../../SECURITY.md)). Fixing them is not a pilot + deliverable. +- **Code quality review** of agent-produced changes. A Certificate shows what + happened, not whether the work was good ([L5](CLAIMS.md#limits-to-disclose)). +- **Onsite work and travel**, unless agreed in writing and billed at cost. + +## Customer responsibilities + +- Name a pilot owner who can make decisions and attend the weekly check-in. +- Provide pilot developers who use Claude Code on the pilot repositories during the + pilot window (at least three working sessions each). +- Provide approvals before kickoff: workstation install exception, hook + registration, and (for CI tiers) permission to add a GitHub Action. +- Hold the issuer private key. We never take custody of it. +- Review and approve every artifact before it is shared with us + ([06-security-and-data-handling.md](06-security-and-data-handling.md)). +- Return the [discovery questionnaire](05-discovery-questionnaire.md) before kickoff. + +Delays caused by missing access or approvals move the timeline without changing +the price. Longer pauses are handled under +[08-pricing.md](08-pricing.md#payment-terms). diff --git a/sales/flight-recorder-pilot/04-deliverables.md b/sales/flight-recorder-pilot/04-deliverables.md new file mode 100644 index 0000000..be2ad10 --- /dev/null +++ b/sales/flight-recorder-pilot/04-deliverables.md @@ -0,0 +1,33 @@ +# Deliverables + +Every deliverable stays in the customer's environment and belongs to the customer. +Items marked **CI** are in Recorder + CI Gate and Evidence Pack. Items marked +**EP** are in Evidence Pack only. + +| # | Deliverable | Format | Tier | Accepted by | +|---|---|---|---|---| +| D1 | **Working capture** in each pilot repository on each pilot developer's workstation, at a pinned Korg commit at or after `781bc41` | Installed hook + per-session ledgers in `~/.korg/sessions/` | All | [AC1](09-acceptance-criteria.md#ac1--capture-works) | +| D2 | **Install and uninstall runbook** for the pilot configuration, including exact hook entries and the rollback step | Markdown | All | [AC1](09-acceptance-criteria.md#ac1--capture-works) | +| D3 | **Verification kit**: verifiers from at least two independent implementations (including Rust `korg-verify` where a Rust toolchain is allowed), plus a one-page "how to verify a session or Certificate" guide for reviewers | Installed tools + Markdown | All | [AC2](09-acceptance-criteria.md#ac2--ledgers-verify-independently) | +| D4 | **Coverage measurement** comparing Claude Code transcripts with ledger events for sampled sessions | Table in the report + script output | All | [AC3](09-acceptance-criteria.md#ac3--coverage-is-measured-and-explained) | +| D5 | **Customer-held issuer key**, its pinned public key, and the chosen sealing model, recorded in the runbook | Key file on a customer machine (never sent to us) | All | [AC5](09-acceptance-criteria.md#ac5--certificates-verify-under-the-pinned-key) | +| D6 | **Sample Certificates** (`korgcert@v1`) for customer-chosen sessions | `.korgcert.json` files | All | [AC5](09-acceptance-criteria.md#ac5--certificates-verify-under-the-pinned-key) | +| D7 | **Drill record**: tamper, deletion, wrong-key, and redaction-canary drills with verifier output | Report appendix with command logs | All | [AC4](09-acceptance-criteria.md#ac4--tampering-is-detected), [AC6](09-acceptance-criteria.md#ac6--secrets-are-redacted-before-hashing) | +| D8 | **Overhead measurement**: hook time per firing against session length on real pilot sessions | Table in the report | All | [AC3](09-acceptance-criteria.md#ac3--coverage-is-measured-and-explained) | +| D9 | **Findings report** and a 60-minute **readout** | PDF or Markdown + meeting | All | [AC8](09-acceptance-criteria.md#ac8--report-and-readout-delivered) | +| D10 | **CI verification gate** on the pilot repositories (verification pinned to the issuer key, plus a redaction-lint step), with a passing PR and a deliberately failing PR as proof | Workflow file + two PR runs | CI | [AC7](09-acceptance-criteria.md#ac7--ci-gate-passes-good-and-fails-bad-ci-tiers) | +| D11 | **Anchoring demonstration** (if the customer opts in to publishing a tip hash, never the Certificate) or a written structural-only alternative | Anchored Certificate + `resolve` output, or memo | CI | [AC8](09-acceptance-criteria.md#ac8--report-and-readout-delivered) | +| D12 | **Codex CLI feasibility finding** from one replayed, customer-sanitized trace | Replay script + verified journal + one-page memo | CI | [AC8](09-acceptance-criteria.md#ac8--report-and-readout-delivered) | +| D13 | **Draft control-evidence matrix** linking pilot artifacts to customer-selected controls, for the customer's auditor to review | Spreadsheet or Markdown table | EP | [AC8](09-acceptance-criteria.md#ac8--report-and-readout-delivered) | +| D14 | **Operating runbook**: rollout, key custody and rotation, retention, redaction incident response, verifier upgrades | Markdown | EP | [AC8](09-acceptance-criteria.md#ac8--report-and-readout-delivered) | +| D15 | **Executive readout** for a second audience | Slides + meeting | EP | [AC8](09-acceptance-criteria.md#ac8--report-and-readout-delivered) | + +## What the customer does not get + +- A certificate of compliance, audit opinion, or legal assessment + ([03 exclusions](03-scope-and-exclusions.md#exclusions--all-tiers)). +- A hosted service, account, or subscription. Nothing needs to be renewed for the + installed tooling to keep working. +- Proprietary software. Everything installed is the public, MIT / Apache-2.0 + Korg code at the pinned commit. Pilot scripts written for the customer are + delivered under the same licenses. diff --git a/sales/flight-recorder-pilot/05-discovery-questionnaire.md b/sales/flight-recorder-pilot/05-discovery-questionnaire.md new file mode 100644 index 0000000..278ca9a --- /dev/null +++ b/sales/flight-recorder-pilot/05-discovery-questionnaire.md @@ -0,0 +1,118 @@ +# Technical discovery questionnaire + +Send this after the scoping call. Answers decide fit, tier, and pilot plan. We +reply within two business days, either confirming the pilot or explaining why +Korg is not a fit. + +Answer only what you can share. Do not include secrets, credentials, source code, +or real session transcripts in your answers. + +--- + +## A. Goals and stakeholders + +1. What question should this pilot answer for you? (For example: "Can we show an + auditor what Claude Code changed?" or "Can we roll Claude Code out to every + team?") +2. Who owns the pilot decision, and who else must approve rollout (security, GRC, + platform, legal)? +3. What triggered this now? (Questionnaire, audit date, incident, rollout plan.) + If there is a date, give it. +4. What happens if the pilot succeeds? What would make you stop it? + +## B. Agents in use + +5. Which coding agents do your engineers use today, and roughly how many people use + each? (Claude Code, Codex CLI, Copilot, Cursor, Windsurf, Gemini CLI, internal + agents, others.) +6. For Claude Code: which version or versions, and how is it run? (Interactive + terminal, IDE extension, headless `claude -p`, inside CI, in containers or + remote dev environments.) +7. Do you use Claude Code subagents, custom hooks, MCP servers, or plugins today? + List any existing hooks so we can avoid conflicts. +8. Do you manage Claude Code settings centrally (managed or enterprise settings)? + Do they restrict user-defined hooks? +9. For Codex CLI (CI tiers only): can you record one representative WebSocket + session trace (for example with mitmproxy) and remove authentication headers and + other secrets before sharing it? We provide a sanitization checklist. If not, we + skip the feasibility item. + +## C. Workstations and environment + +10. Pilot developers' operating systems and versions. (macOS and Linux are in + scope. Windows is not.) +11. Can pilot developers install Python 3.10+ packages from a local checkout of a + public Git repository (with `--no-deps`), plus `cryptography` from your usual + index? Is there a proxy or package mirror we must use? +12. Can we build a Rust binary (`korg-verify`) on at least one customer machine or + CI runner? It is the third independent verifier and lints Certificates for + secrets directly. Without it, verification uses Python and JavaScript only. +13. Are home directories on network storage or synced (iCloud, OneDrive, roaming + profiles)? Ledgers are written under `~/.korg`. +14. What endpoint security (EDR, application allow-listing) might flag a new hook + process? + +## D. Repositories and CI + +15. Which repositories are in the pilot? Give the approximate size and language, and + say whether each one is public or private. +16. Code host and CI system. (The CI gate requires GitHub Actions.) +17. Can we add a workflow that runs a composite action from the public Korg + repository, pinned to a commit? Certificates contain full session content: may + reviewed Certificates be committed to the pilot repositories, or must CI fetch + them from a private store? PR comments show the claim, tool counts, and file + paths, and the action posts them by default. Should we turn them off? +18. Is there a public GitHub repository where you would commit a file containing + only a tip hash, for public anchoring? (Optional. Only the hash and the commit + become public, never the Certificate or ledger content.) + +## E. Data sensitivity + +19. Classification of the code and data that agents touch in the pilot repositories + (public, internal, confidential, regulated). Do agents ever see production + data, customer data, or personal data? +20. Ledgers record prompts, commands, file paths, file contents read, and command + output. Who may hold these records, and where? +21. Which secret formats are common in your environment beyond standard + provider keys? (Internal token prefixes, connection strings, vault paths.) We + test redaction coverage against these, using synthetic values only. +22. What may we see during the pilot? Choose one: (a) nothing; we work only on + screen-share, (b) verifier output and summaries only, (c) selected + customer-reviewed Certificates, (d) a customer-provisioned sandbox. +23. Do we need to sign a specific NDA, DPA, or security addendum before kickoff? + +## F. Audit and governance context + +24. Which frameworks or obligations apply? (SOC 2, ISO/IEC 27001, ISO/IEC 42001, + PCI DSS, HIPAA, NIST AI RMF, EU AI Act, customer contracts, internal policy.) + When are the next audit dates? +25. Have auditors, customers, or regulators asked about AI-assisted development? If + you can share the wording of a question, it helps us focus the report. +26. How long must change and logging records be kept under your current policy? +27. Who should hold the issuer signing key after the pilot (security, platform, + a release engineer)? Do you use an HSM or secrets manager for signing keys today? + +## G. Logistics + +28. Preferred start date, and any blackout dates (releases, holidays, audit + fieldwork). +29. Pilot developers: names or roles, time zones, and how many Claude Code working + sessions each expects to run on pilot repositories during the pilot window. +30. Tier you are considering (Recorder, Recorder + CI Gate, Evidence Pack) and + anything in [03-scope-and-exclusions.md](03-scope-and-exclusions.md) you would + like to change. + +--- + +## How we use your answers + +| Answer (question number) | Effect | +|---|---| +| No Claude Code use (Q5) | Not a fit for live capture. We say so and stop. | +| Hooks blocked by managed settings, with no exception (Q8) | Not a fit until an exception is granted. | +| Windows-only pilot developers (Q10) | Not a fit. | +| No GitHub Actions (Q16) | Recorder tier only. | +| No public anchoring repository (Q18) | Structural-only anchoring memo replaces the live demonstration. | +| No Rust toolchain anywhere (Q12) | Python and JavaScript are the two independent verifiers; Certificates are linted through their extracted events with the Python lint. | +| Regulated or personal data visible to agents (Q19) | We recommend option (a) or (b) in Q22, and extra canary tests based on Q21. | +| Audit date within 8 weeks (Q24) | We recommend Evidence Pack and an early start, and we flag that the pilot's evidence window will be short. | diff --git a/sales/flight-recorder-pilot/06-security-and-data-handling.md b/sales/flight-recorder-pilot/06-security-and-data-handling.md new file mode 100644 index 0000000..eb7df01 --- /dev/null +++ b/sales/flight-recorder-pilot/06-security-and-data-handling.md @@ -0,0 +1,207 @@ +# Security and data-handling terms + +These terms describe how the pilot handles customer data. They are written to be +attached to the SOW and read by the customer's security reviewer. If they conflict +with a signed NDA, DPA, or MSA, the signed agreement wins. + +## 1. What the pilot records + +The Claude Code capture hook is registered only in the pilot repositories, so it +records only Claude Code sessions started there +([L16](CLAIMS.md#limits-to-disclose)). It writes one ledger per session, which can +contain: + +- the developer's prompts and the model's responses, as they appear in the session + transcript; +- every tool call and its arguments, such as file paths, shell commands, and edit + contents; +- tool results, such as file contents read, command output, and test output + (each truncated at 8,000 characters); +- session identifiers, the agent label, ledger ordering clocks, and hash-chain + fields. + +**A Certificate embeds the same events as the ledger it was minted from** +([L15](CLAIMS.md#limits-to-disclose)). **Treat ledgers and Certificates as +confidential source code.** They hold much of what the developer's Claude Code +transcript already holds on the same machine. + +## 2. Where data lives + +- **Customer environment only, by default.** Capture, sealing, and verification run + on customer workstations and customer CI. Ledgers are written under `~/.korg` on + the developer's machine. +- **No hosted service.** The pilot deploys no Korg server, collector, or + dashboard, and it sends no telemetry to us or to anyone else. `korg-server` and + `mcp_server.py` are not deployed, because Korg v1 is designed for local, + single-user workspaces ([L8](CLAIMS.md#limits-to-disclose)). +- **Browser verifiers run locally.** The hosted verifier pages check the file in + the reviewer's browser and do not upload it. The pages do load web fonts from + Google Fonts. Customers who prefer can serve the same pages from their own host. +- **Network access by Korg tooling during the pilot** is limited to: cloning the + public Korg repository; installing Python build and runtime dependencies from + the customer's package index; fetching Rust crates from crates.io (or a mirror) + to build `korg-verify`; GitHub Actions fetching the pinned action; loading the + hosted verifier pages, if used; the CI action's PR comment through the GitHub + API, if enabled; and, only if the customer opts in, `korg-seal resolve` calling + the public GitHub API for an anchored commit. Ledger content is never sent in + any of these. + +## 3. Vendor access + +- **No standing access.** We do not ask for accounts on customer repositories, + workstations, or CI. Work happens over customer-hosted screen-share, or in a + customer-provisioned sandbox if the customer chooses one. +- **Customer-approved sharing only.** We receive only artifacts the customer has + reviewed and approved, at the level chosen in + [questionnaire item 22](05-discovery-questionnaire.md#e-data-sensitivity): + nothing, verifier output and summaries, selected Certificates (which contain full + session content), or sandbox access. +- **Approved artifacts** travel over a customer-chosen channel (for example the + customer's file share). We do not upload them to public repositories, issue + trackers, or other third-party services. +- **No AI processing of customer data** without written approval. We will not paste + customer ledgers, transcripts, or code into third-party AI services. +- **Bug reports upstream** never include customer data. Reproductions use synthetic + data. Security issues go through the private GitHub Security Advisory channel + in Korg's [SECURITY.md](../../SECURITY.md). That file's supported-versions table + predates v0.2.0, so we report through that channel whatever the version. + +## 4. Secrets and redaction + +- **Redaction before hashing.** The hook writes through `LedgerWriter`, which + applies the `korg-redact@v1` policy before an event is hashed or written. It + replaces recognized secrets with `[REDACTED:]` markers that carry no + hash, prefix, or length of the secret ([C8](CLAIMS.md#claims-you-may-make)). +- **Redaction is rule-based, not DLP.** It covers sensitive key names and the + listed credential patterns. Internal token formats, personal data, customer + data, and proprietary code are recorded as-is ([L6](CLAIMS.md#limits-to-disclose)). +- **Canary drill.** In the first week we plant synthetic secrets (never real ones) + in each format from [questionnaire item 21](05-discovery-questionnaire.md#e-data-sensitivity), + run them through a real session, and record which formats are redacted. Formats + that are not redacted are reported as findings, with mitigations. +- **Lint.** Every pilot ledger is checked with `python -m korg_ledger lint` or + `korg-verify --require-redacted`, and Certificates are minted only from ledgers + that pass. Every Certificate is checked too: with `korg-verify --require-redacted` + where a Rust toolchain is allowed, otherwise by running the Python lint over the + Certificate's extracted events. The CI gate runs the same redaction-lint step, + because the `verify-korgcert` action does not check redaction. +- **Remediation without tampering.** A ledger that is found to contain a secret is + not edited in place. It is re-chained into a new, clean journal with + `python -m korg_ledger rechain-redacted`, and the original is deleted under the + customer's procedure. **The exposed secret must be rotated.** If the secret + also reached a Certificate that was committed to git or attached to a PR, + removing it means rewriting that history, which is one reason the CI gate can + read Certificates from a private store instead. +- **Excluded component.** The `stream-json` adapter stores large payloads in + `.korg/blobs/` without redaction, so the pilot does not use it + ([L7](CLAIMS.md#limits-to-disclose)). + +## 5. Keys + +- **The customer generates and holds the issuer key.** `korg-seal` creates a 32-byte + Ed25519 seed at `~/.korg/issuer.ed25519` with mode `0600`, or at a path the + customer chooses. We never receive, copy, or escrow a customer private key. +- **Pinning.** Verification in CI and in the runbook pins the issuer public key. A + Certificate signed by any other key fails. +- **Who seals, and when.** A session ledger lives on the developer's machine. Until + it is sealed, it can be rewritten there by anyone with that user's access, + including the agent itself, since its shell tool runs as the same user + ([L2](CLAIMS.md#limits-to-disclose)). Once it is sealed into a Certificate and + that Certificate leaves the machine (committed for CI, stored centrally, or + anchored), later edits are detected. In the pilot, the customer chooses one of + two models, and the report records the trade-off and the measured time between + capture and sealing: + - **(a) Designated key holder (recommended).** A named person, such as a release + engineer, seals ledgers that developers submit. Developers never hold the key. + - **(b) Shared team key.** Each pilot developer seals with a copy of the team key + at PR time. This is simpler, but it puts one private key on every pilot laptop, + and any of those developers could rewrite and re-seal a session before + submitting it. +- **No revocation.** `korgcert@v1` has no revocation mechanism. If a key leaks, its + past seals stay valid for anyone who still pins it. Recovery means generating a + new key, pinning it everywhere (CI, runbook, reviewers), and treating seals from + the old key as untrusted from the leak date onward + ([L3](CLAIMS.md#limits-to-disclose)). +- **What a signature means.** A valid seal proves that the holder of that key + signed the record. It does not identify a person or organization; that binding + is the customer's key custody ([L3](CLAIMS.md#limits-to-disclose)). +- **HMAC keying is not used in the pilot.** The ledger library supports + HMAC-keyed chains, which cannot be forged without the key, but the Claude Code + hook does not expose a key setting today. Pinned Certificates, which are held + outside the developer's machine, provide the trusted tip instead + ([L2](CLAIMS.md#limits-to-disclose)). + +## 6. Publishing and anchoring (opt-in) + +Public anchoring commits a small file that contains **only** a Certificate's tip +hash to a **public** GitHub repository. `korg-seal anchor` then binds that commit +into the Certificate, and `korg-seal resolve` lets anyone confirm the commit added +the hash. + +- **Never publish the Certificate itself** to anchor it. The `korg-seal` README + example commits the whole seal; in the pilot we commit only the hash, because a + Certificate contains full session content ([L15](CLAIMS.md#limits-to-disclose)). +- **What becomes public:** a SHA-256 hash, the commit, and the repository name. A + hash reveals nothing practical about the session, but the customer decides + whether to publish at all. +- **What it proves:** the hash was in that public commit. The commit date is + self-asserted by git, so the dependable bound is "before any third party fetched + or mirrored the commit." It is not a trusted timestamp + ([L4](CLAIMS.md#limits-to-disclose)). +- **Without a public repository,** anchoring is structural only and gives no time + bound. + +## 7. Retention and deletion + +- **The customer owns all ledgers, Certificates, and reports** and sets their + retention under its own policy. +- **Vendor copies.** We delete any customer artifacts we hold within 30 days of + acceptance, or sooner on request, and confirm the deletion in writing. Exception: + the final report and SOW, which we keep under the NDA as business records unless + the customer asks us to delete them too. +- **Certificates in git.** If the customer has CI read Certificates committed to a + repository, their content lives in git history and is subject to that + repository's retention. Deleting it later means rewriting history. +- **Uninstall.** The runbook includes removing the hook entries. Uninstalling does + not delete ledgers; the customer deletes or archives them under its retention + policy. + +## 8. Software supply chain + +- All installed components are public, MIT / Apache-2.0 Korg code, installed from + a local checkout at a commit SHA (at or after `781bc41`) recorded in the runbook + and the report. +- Korg's Python packages are not on PyPI, and `claude-code-adapter` declares a + dependency on `korg-ledger-py`, a name that was not registered there as of + 2026-10-13. To rule out dependency confusion, the Korg packages are installed + from the checkout with `--no-deps`. Third-party Python packages (`cryptography` + and its dependencies, plus the `setuptools` and `wheel` build tools) come from the + customer's usual index ([L10](CLAIMS.md#limits-to-disclose)). +- Building `korg-verify` pulls its locked Rust dependencies (for example + `sha2`, `hmac`, `ed25519-dalek`, `serde_json`, `regex`) from crates.io or the + customer's mirror, pinned by the repository's `Cargo.lock`. +- The stale `@korgg/ledger-verify` npm package and `korg-verify` crates.io release + (both 0.1.0) are not used. The JavaScript verifier runs from the checkout. +- The runbook lists exact versions of everything installed. +- The redaction, lint, and nested-journal checks the pilot relies on landed on + `main` after v0.2.0 and are recent. The pilot exercises them on the customer's + own sessions rather than assuming them. +- The CI action is referenced by commit SHA, not by branch. + +## 9. Incident handling during the pilot + +If either party finds a secret exposure, unexpected data flow, or a vulnerability +in Korg during the pilot: + +1. The finder tells the other party's named contact within one business day. +2. Capture is paused on affected machines if the customer asks. +3. Secret exposures follow section 4 (re-chain, delete, rotate). +4. Korg vulnerabilities go through the private advisory channel in + [SECURITY.md](../../SECURITY.md), never a public issue. + +## 10. No certification + +The pilot and its outputs are not a certification, attestation, audit opinion, or +legal advice. We make no representation that using Korg satisfies any law, +regulation, standard, or contract. Draft control-evidence mappings (Evidence Pack) +are working material for the customer and its auditors to review. diff --git a/sales/flight-recorder-pilot/07-timeline.md b/sales/flight-recorder-pilot/07-timeline.md new file mode 100644 index 0000000..23cf099 --- /dev/null +++ b/sales/flight-recorder-pilot/07-timeline.md @@ -0,0 +1,79 @@ +# Pilot timeline + +Durations count from kickoff and match [README.md](README.md#pilot-at-a-glance): +Recorder 2 weeks, Recorder + CI Gate 3 weeks, Evidence Pack 4 weeks. Pre-kickoff +work (week 0) is not counted. + +## Week 0 — before kickoff (customer-paced, usually 1–2 weeks) + +| Step | Owner | Exit condition | +|---|---|---| +| Scoping call (30 min) | Both | Tier chosen; ICP checklist passes ([02](02-ideal-customer-profile.md#qualification-checklist-first-call)) | +| Discovery questionnaire returned | Customer | [05](05-discovery-questionnaire.md) answered | +| Fit confirmation | Vendor | Written go/no-go within 2 business days | +| Security review of [06](06-security-and-data-handling.md); NDA and SOW signed | Customer | Signed; first 50% invoice issued | +| Approvals: workstation install, hook registration, CI action (CI tiers) | Customer | Approvals in writing | +| Pilot developers and calendar confirmed | Customer | Names and kickoff date | + +## Recorder — 2 weeks + +| Day | Activity | Output | +|---|---|---| +| 1 | Kickoff (60 min): goals, acceptance criteria walkthrough, data-sharing level | Agreed plan | +| 1–2 | Install on pilot workstations at a pinned commit; verifiers set up; issuer key generated by the customer | D1, D2, D3, D5 | +| 2–3 | Redaction canary drill with synthetic secrets | First half of D7 | +| 3–8 | Developers work normally on pilot repositories; daily ledger verification spot checks | Ledgers accumulate | +| 5 | Mid-pilot check-in (30 min): early coverage and overhead numbers | Issues list | +| 6–8 | Coverage and overhead measurement; optional backfill | D4, D8 | +| 8–9 | Certificates minted for customer-chosen sessions; tamper and wrong-key drills | D6, rest of D7 | +| 9 | Acceptance run ([09](09-acceptance-criteria.md)) | Criteria results | +| 10 | Report delivered; readout (60 min) | D9 | + +## Recorder + CI Gate — 3 weeks + +Days 1–9 follow the Recorder plan (install, canary drill, capture, measurement, +Certificates, and tamper drills). Its acceptance run and report move to the end. +Then: + +| Day | Activity | Output | +|---|---|---| +| 10–11 | Add the CI gate (`verify-korgcert` action pinned to the issuer key, plus a redaction-lint step, PR comments off unless chosen) to the pilot repositories; one passing PR and one deliberately failing PR, using day-8–9 Certificates | D10 | +| 10–12 | Anchoring demonstration (if opted in) or structural-only memo | D11 | +| 11–12 | Codex CLI feasibility replay of one customer-sanitized trace | D12 | +| 13 | Acceptance run | Criteria results | +| 14–15 | Report and readout | D9 | + +## Evidence Pack — 4 weeks + +Days 1–12 follow the Recorder + CI Gate plan. Its acceptance run and report move +to week 4, so acceptance runs once, at the end: + +| Day | Activity | Output | +|---|---|---| +| 13–15 | Extra capture and measurement time for the larger pilot group; findings consolidated | D4, D8 updated | +| 16 | Control-evidence mapping workshop (half day) with the GRC owner | Draft D13 | +| 16–18 | Operating runbook drafted and reviewed with platform and security owners | D14 | +| 18 | Acceptance run | Criteria results | +| 19 | Report and team readout | D9 | +| 20 | Executive readout | D15 | + +## After acceptance + +| When | What | +|---|---| +| On acceptance | Final 50% invoiced, payable net 15 ([08](08-pricing.md#payment-terms)) | +| Through support window (14 or 30 days) | Async support by email for the installed configuration | +| Acceptance + 30 days | Vendor deletes any customer artifacts it holds and confirms in writing ([06 §7](06-security-and-data-handling.md#7-retention-and-deletion)) | + +## Schedule risks we watch + +- **Too few real sessions.** Coverage numbers need real work. If pilot developers + are behind the three-session minimum at the mid-pilot check-in, we agree a + catch-up plan. The options are: the customer accepts a smaller sample in writing; + we extend once by up to 5 business days at no cost; or the customer buys an + additional pilot week ([08](08-pricing.md#change-orders)). +- **Approvals arriving after kickoff.** These pause the clock + ([03](03-scope-and-exclusions.md#customer-responsibilities)). +- **Claude Code updates mid-pilot.** A new Claude Code release can change the + transcript format. We record the version in every measurement and re-run + coverage checks if it changes. diff --git a/sales/flight-recorder-pilot/08-pricing.md b/sales/flight-recorder-pilot/08-pricing.md new file mode 100644 index 0000000..a455531 --- /dev/null +++ b/sales/flight-recorder-pilot/08-pricing.md @@ -0,0 +1,112 @@ +# Pricing options + +All prices are fixed, in USD, exclusive of taxes, for remote delivery. Scope per tier +is in [03-scope-and-exclusions.md](03-scope-and-exclusions.md); the canonical +summary is in [README.md](README.md#pilot-at-a-glance). + +## Tiers + +### Recorder — $6,500 · 2 weeks + +For a team that wants to know whether Claude Code sessions can be recorded, +redacted, and independently verified on its own machines. + +- 1 repository, up to 5 pilot developers on Claude Code +- Capture, verification kit, customer-held issuer key, sample Certificates +- Tamper, wrong-key, and redaction-canary drills +- Coverage and overhead measurement +- Findings report and 60-minute readout +- 14 days of async support after acceptance + +### Recorder + CI Gate — $14,500 · 3 weeks *(recommended)* + +For a team that wants verification wired into pull requests, so reviewers stop +taking an agent transcript on trust. + +Everything in Recorder, plus: + +- Up to 2 repositories, up to 10 pilot developers +- `verify-korgcert` GitHub Action pinned to the customer's issuer key, proven with + one passing PR and one deliberately failing PR +- Public git-tip anchoring demonstration (opt-in; publishes a hash only) or + structural-only memo +- Codex CLI feasibility replay of one sanitized trace +- 30 days of async support after acceptance + +### Evidence Pack — $24,000 · 4 weeks + +For a team with an audit, enterprise deal, or board question on the calendar, +which needs the pilot output in a form its GRC owner can take to an auditor. + +Everything in Recorder + CI Gate, plus: + +- Up to 3 repositories, up to 20 pilot developers +- Half-day control-evidence mapping workshop, producing a draft evidence matrix + for the customer's own selected controls (not an audit opinion) +- Operating runbook: rollout, key custody and rotation, retention, redaction + incidents, verifier upgrades +- Executive readout for a second audience +- 30 days of async support after acceptance + +## Comparison + +| | Recorder | Recorder + CI Gate | Evidence Pack | +|---|---|---|---| +| Price | $6,500 | $14,500 | $24,000 | +| Duration | 2 weeks | 3 weeks | 4 weeks | +| Repositories | 1 | up to 2 | up to 3 | +| Pilot developers | up to 5 | up to 10 | up to 20 | +| Deliverables | D1–D9 | D1–D12 | D1–D15 | +| Support after acceptance | 14 days | 30 days | 30 days | + +Deliverable numbers refer to [04-deliverables.md](04-deliverables.md). + +## Payment terms + +- **50% at signature**, invoiced with the SOW and payable before kickoff. +- **50% on acceptance**, invoiced when the pilot is accepted under + [09-acceptance-criteria.md](09-acceptance-criteria.md#acceptance-process), + payable net 15. +- **Fit check and early exit.** If the discovery questionnaire shows Korg cannot capture the + customer's agents, we decline before any invoice. If a hard blocker that was + not disclosed in discovery appears in the first three business days after + kickoff (for example, hooks blocked by policy with no exception), the customer + may cancel and we refund the first payment minus $1,500 for work performed. +- **Pause.** If the customer pauses the pilot for more than 15 business days, the + remaining work is rescheduled by mutual agreement. A pause longer than 60 + business days ends the pilot. In that case we invoice delivered work pro rata, + capped at the remaining balance. + +## Change orders + +Work outside the selected tier's scope is quoted in writing before it starts: + +| Item | Price | +|---|---| +| Additional repository (within the same CI setup) | $1,500 each | +| Additional 5 pilot developers | $1,500 per block | +| Additional pilot week (more capture and measurement time) | $3,500 | +| Upgrade between tiers during the pilot | Difference in price; timeline extends to the higher tier's duration | +| Other out-of-scope work | $2,000 per day, quoted as a fixed amount before work starts | + +## Discounts + +Discounts never change scope or acceptance criteria. + +- **Design partner:** 20% off any tier if the customer agrees to a named + case study or a public reference quote after acceptance, with the customer's + approval of every word. +- **Upfront payment:** 5% off for paying 100% at signature. +- Only one discount applies. + +## Price guidance for sellers + +- **Lead with Recorder + CI Gate.** It is the smallest tier that changes a + reviewer's daily workflow (a pass or fail on the PR), which is the strongest + rollout argument. +- **Offer Recorder** when the buyer needs a low-risk first step or has no GitHub + Actions. +- **Offer Evidence Pack** only when there is a dated audit, deal, or board ask, and + only with the "draft for your auditor, not an audit" framing. +- Prices are a starting point for the first pilots and should be revisited after the + first three closed deals, based on actual effort. diff --git a/sales/flight-recorder-pilot/09-acceptance-criteria.md b/sales/flight-recorder-pilot/09-acceptance-criteria.md new file mode 100644 index 0000000..5d7e6bc --- /dev/null +++ b/sales/flight-recorder-pilot/09-acceptance-criteria.md @@ -0,0 +1,145 @@ +# Acceptance criteria + +The pilot is accepted when every criterion for the selected tier passes. Each +criterion is checked with commands the customer runs, or watches run, on its own +machines. The "Known limitations" below were disclosed before signature. They are +not criteria, and they cannot be used to waive one. + +"Two independent verifiers" means verifiers from two different implementations: +Rust, Python, or JavaScript. The Node.js CLI and the browser pages run the same +JavaScript code, so they count as one. The commands for each check are in +[which verifier checks what](CLAIMS.md#which-verifier-checks-what): + +- **Ledgers:** `korg-verify`, `python -m korg_ledger lint`, or `verify.mjs` + (Node or browser). +- **Certificates:** `korg-verify --pubkey`, `korg-seal verify --pin`, or + `verify.mjs --pubkey` (Node or browser). `korg_ledger lint` cannot read + Certificates. + +## AC1 — Capture works + +- The capture hook is registered in each pilot repository for every pilot + developer, at the commit SHA recorded in the runbook (D2). +- At least **3 working sessions per pilot developer** on pilot repositories each + produce a per-session ledger in `~/.korg/sessions/`. +- A Claude Code session started outside the pilot repositories produces no ledger. +- No pilot developer reports a Claude Code session failing or blocking because of + the hook. Any slowdown is recorded under AC3. +- Uninstalling with the runbook removes the hook entry and leaves the ledgers in place. + +## AC2 — Ledgers verify independently + +- **Every pilot ledger** verifies as VALID (chain intact, causal DAG well-formed) + under **two independent verifiers**, and the two agree. Redaction findings from + `korg_ledger lint` are judged under AC6, not here. +- Any ledger that fails is investigated and its root cause is written up. If the + cause is a Korg defect, we report it upstream. The criterion still fails, unless + the customer accepts in writing with the defect listed as a finding. + +## AC3 — Coverage is measured and explained + +- For at least **10 sampled sessions** (or every session, if there are fewer than + 10), the report compares the number of `tool_use` blocks in the Claude Code + transcript with the tool-call events in the ledger, per tool name. +- Every difference is explained in the report (for example, a tool call with no + result because the session ended). Unexplained differences fail this criterion. +- Hook overhead (time per firing compared with transcript size) is measured on + real pilot sessions and reported with the Claude Code version. **No overhead + threshold is promised.** The number is a finding for the rollout decision. + +## AC4 — Tampering is detected + +On copies of real pilot ledgers, in front of the customer: + +| Drill | Expected result | +|---|---| +| Change one character in one event's content | Every verifier reports INVALID, names the edited `seq`, and exits non-zero | +| Delete one event from the middle | INVALID, localized to the break | +| Swap the order of two events | INVALID | +| Edit a Certificate's summary (for example, remove a file from `files`) | Certificate INVALID (summary does not match the events) | +| Verify a valid Certificate with a different pinned key | INVALID (issuer does not match pinned key) | + +All five drills produce the expected result in two independent verifiers. + +## AC5 — Certificates verify under the pinned key + +- The customer generates the issuer key on a customer machine. The private seed is + never transferred to the vendor. +- At least **3 Certificates** are minted from real pilot sessions chosen by the + customer. +- Each Certificate verifies as VALID with the customer's public key pinned, in two + independent verifiers. Reviewers are also shown the browser page. +- The developer reviews each Certificate summary (agents, tool counts, file paths + from file-tool arguments, seq range) against their memory of the session. Any + mismatch is a finding. Files changed only through shell commands are expected to + be missing from `files` ([L14](CLAIMS.md#limits-to-disclose)). + +## AC6 — Secrets are redacted before hashing + +- Synthetic canary secrets, one per format from + [questionnaire item 21](05-discovery-questionnaire.md#e-data-sensitivity) plus at + least one standard provider key and one bearer token, are passed through a real + Claude Code session (for example, echoed in a shell command). +- For every format covered by `korg-redact@v1`, the ledger contains the + `[REDACTED:]` marker and **does not contain the raw canary value**, and the + ledger still verifies. +- Formats that are not covered are listed in the report with a mitigation. They + are a finding, not a failure, because coverage of customer-specific formats is a + [disclosed limit](CLAIMS.md#limits-to-disclose). +- Every pilot ledger passes the redaction lint (`python -m korg_ledger lint` or + `korg-verify --require-redacted`), and every Certificate is minted from a ledger + that passed. Every Certificate also passes the lint: `korg-verify + --require-redacted`, or the Python lint over its extracted events + ([how](CLAIMS.md#which-verifier-checks-what)). A ledger that fails is remediated with + `rechain-redacted`, and the exposed secret is rotated + ([06 §4](06-security-and-data-handling.md#4-secrets-and-redaction)). + +## AC7 — CI gate passes good and fails bad (CI tiers) + +- The CI gate runs on the pilot repositories: the `verify-korgcert` action, + referenced by commit SHA and pinned to the customer's issuer key, plus a + redaction-lint step. +- A PR with a valid Certificate passes the job. +- A PR with a deliberately tampered Certificate fails the job, and the job output + names the problem. +- A PR with a Certificate signed by a different key fails the job. + +## AC8 — Report and readout delivered + +- The findings report follows [10-sample-report-outline.md](10-sample-report-outline.md) + and includes every tier deliverable (D9, plus D11–D12 for CI tiers and D13–D15 + for Evidence Pack). +- The readout is held with the pilot owner. For Evidence Pack, the executive + readout is held too. +- The report's appendix lists the exact commit SHA, package versions, Claude Code + version, and the commands used, so the customer can reproduce every result. + +## Known limitations (not criteria) + +These are disclosed before signature ([CLAIMS.md](CLAIMS.md#limits-to-disclose)). +The pilot does not test for them, so they cannot fail it, and they cannot excuse a +failed criterion either: + +- No live capture of agents other than Claude Code. +- A ledger can be rewritten undetectably before it is sealed, including by the + agent itself. +- No trusted timestamp; public anchoring requires a public GitHub repository. +- Signatures prove a key, not a person, and there is no revocation. +- Redaction does not cover formats outside `korg-redact@v1`. +- Tool results longer than 8,000 characters are truncated, and the summary's + `files` list covers file-tool arguments only. +- Actions outside Claude Code (for example, manual edits by the developer) are not + recorded. + +## Acceptance process + +1. The vendor runs the acceptance checks with the customer and sends the results + with the report. +2. The customer has **5 business days** to accept or to list, in writing, the + criteria it believes failed. +3. The vendor fixes listed failures within **5 business days** and re-runs only + those criteria. +4. If the customer neither accepts nor lists failures within 5 business days of + receiving the report, the pilot is deemed accepted. +5. Criteria blocked by missing customer access or approvals are rescheduled, not + failed ([03](03-scope-and-exclusions.md#customer-responsibilities)). diff --git a/sales/flight-recorder-pilot/10-sample-report-outline.md b/sales/flight-recorder-pilot/10-sample-report-outline.md new file mode 100644 index 0000000..3574025 --- /dev/null +++ b/sales/flight-recorder-pilot/10-sample-report-outline.md @@ -0,0 +1,145 @@ +# Sample findings report outline + +This is the structure of the report delivered as D9. Example values are shown in +*italics* to show the level of detail; they are illustrative, not results from a +real customer. Sections marked **CI** or **EP** appear only in those tiers. + +--- + +## Agent Flight-Recorder Pilot — Findings Report + +**Customer:** {{CUSTOMER}} · **Tier:** {{TIER}} · **Pilot window:** {{START}}–{{END}} +**Korg commit:** {{KORG_SHA}} · **Claude Code version(s):** {{CC_VERSIONS}} +**Prepared by:** {{SELLER_NAME}} · **Classification:** Customer Confidential + +> This report presents evidence gathered during a technical pilot. It is not a +> certification, attestation, audit opinion, or legal advice. + +### 1. Executive summary (one page) + +- The question the pilot set out to answer, in the customer's words. +- **Recommendation:** roll out / roll out with conditions / do not roll out, with + the two or three reasons that decide it. +- Headline numbers: *sessions captured: 41 across 5 developers · ledgers verified: + 41/41 in two verifiers · tool-call coverage in sampled sessions: 612/615, with all + 3 gaps explained · canary formats redacted: 7/9 · median hook time per firing: + measured value*. +- Acceptance criteria status (AC1–AC8): one line each. + +### 2. Scope and environment + +- Repositories, pilot developers (roles, not names, unless the customer prefers + names), operating systems, Claude Code versions and run modes. +- What was installed, where, and at which commit SHA. +- Data-sharing level used ([06](06-security-and-data-handling.md#3-vendor-access)). +- Deviations from the SOW and the reasons for them. + +### 3. How the record works (one page, for non-engineers) + +- Capture → redaction → hash chain → Certificate → independent verification, as + a simple diagram. +- What a green verification proves, and what it does not + ([CLAIMS.md](CLAIMS.md#limits-to-disclose)), in plain language. + +### 4. Capture results (AC1, AC3) + +- Sessions captured per developer and per repository. +- Coverage table for sampled sessions: + + | Session | Transcript tool calls | Ledger tool events | Difference | Explanation | + |---|---|---|---|---| + | *s-0193…* | *48* | *48* | *0* | — | + | *s-01a2…* | *77* | *76* | *1* | *Session ended before the last `Bash` result was written* | + +- Scope check: no ledgers from sessions outside the pilot repositories. +- Subagent sessions: how they appear (sidechain events are flattened into the + parent session). +- Backfill results, if used. + +### 5. Integrity verification (AC2) + +- Verdicts per verifier implementation, and their agreement. +- Any failing ledger, with its root cause. + +### 6. Tamper drills (AC4) + +- One row per drill: what was changed, the expected result, each verifier's actual + output (verbatim), and pass or fail. + +### 7. Redaction and secrets (AC6) + +- Canary formats tested; redacted or not; the rule that matched. +- Lint results across all pilot ledgers. +- Uncovered formats and recommended mitigations (for example, rename internal + token variables to match a sensitive-key rule, or keep those secrets out of agent + sessions). +- Any real secret found in a ledger, how it was remediated, and confirmation of + rotation (identifiers only, never values). + +### 8. Certificates and keys (AC5) + +- Certificates minted: session, claim, summary, verification output under the + pinned key. +- Sealing model chosen ([06 §5](06-security-and-data-handling.md#5-keys)), the + measured time between capture and sealing, and recommendations for key custody. + +### 9. CI verification gate — **CI** (AC7) + +- Workflow configuration: action referenced by SHA, pinned key, redaction-lint + step, where Certificates are read from, and whether PR comments are on. +- Links to the passing and deliberately failing PR runs, with job output. +- A recommended policy for which PRs should carry a Certificate. + +### 10. Public anchoring — **CI** + +- Anchored Certificate and `korg-seal resolve` output, or the structural-only memo + explaining what the customer gives up without a public anchor. + +### 11. Second-agent feasibility (Codex CLI) — **CI** + +- What was replayed, verification result, causal-structure observations. +- What production capture would require, and an honest estimate of effort. + +### 12. Performance and developer experience + +- Hook time per firing compared with transcript size, measured on real sessions. + Include the method and the machine types. +- Developer feedback: any perceived slowdown, confusion, or friction. +- Disk use of `~/.korg` per developer per week. + +### 13. Gaps, risks, and limits + +- Product limits that affect this customer, cross-referenced to + [CLAIMS.md](CLAIMS.md#limits-to-disclose). +- Defects found and reported upstream (public issue links; security issues + referenced only by private advisory). +- Operational risks of a rollout (for example key custody, ledger retention on + laptops, Claude Code upgrades changing the transcript format). + +### 14. Control-evidence mapping — **EP** + +- Draft matrix. Columns: customer-selected control (ID and text, as the customer + chose them), the evidence artifact, how a reviewer verifies it, its limits, and + the owner. Example rows the customer might select: *SOC 2 CC8.1 (change + management)*, *ISO/IEC 27001:2022 Annex A 8.15 (logging) and 8.32 (change + management)*. +- A statement that the matrix is a draft for the customer's auditor to evaluate. + +### 15. Recommendations and 90-day plan + +- Rollout decision and conditions. +- Concrete next steps with owners: wider capture group, CI policy, key custody, + retention, redaction hardening, monitoring of upstream Korg releases. +- What to re-measure after 90 days. + +### Appendices + +- A. Exact commands used for every acceptance check, so the results can be + reproduced. +- B. Versions: Korg commit SHA, Python package versions, Node.js version, Claude Code + versions, operating systems. +- C. SHA-256 of every artifact referenced in the report (ledgers, Certificates). +- D. Verbatim verifier output for drills and Certificates. +- E. Glossary: ledger, hash chain, tip, causal DAG, Certificate, issuer key, + pinning, anchor, redaction marker. +- F. Operating runbook (**EP**), or a link to it. diff --git a/sales/flight-recorder-pilot/11-outreach-templates.md b/sales/flight-recorder-pilot/11-outreach-templates.md new file mode 100644 index 0000000..b9cf3a3 --- /dev/null +++ b/sales/flight-recorder-pilot/11-outreach-templates.md @@ -0,0 +1,251 @@ +# Outreach templates + +Templates for first-touch and follow-up messages to teams using coding agents. +**Nothing in this kit has been sent to anyone.** A person sends each message +individually, after doing the research below. + +## Before you write + +Every message must include at least one specific, verifiable fact about the +prospect. If you cannot find one, do not send. + +| Token | What to put there | Where to find it | +|---|---|---| +| `{{FIRST_NAME}}` | Recipient's first name | Profile, company site | +| `{{COMPANY}}` | Company name | — | +| `{{AGENT_SIGNAL}}` | Evidence that they use Claude Code: a blog post, talk, job listing, `CLAUDE.md` in a public repo, a public Claude Code hook or config | Engineering blog, GitHub, job boards, conference talks | +| `{{AUDIT_SIGNAL}}` | Evidence of audit exposure: trust page listing SOC 2 / ISO 27001, a regulated industry, enterprise customers | Trust center, security page, customer logos | +| `{{TRIGGER}}` | A recent, dated reason this matters now: rollout announcement, AI-governance hire, published AI policy, incident write-up | News, blog, job boards | +| `{{SELLER_NAME}}`, `{{SELLER_EMAIL}}` | You | — | + +Rules: + +- **Claude Code users only** for the live-capture pitch. If the only signal is + Copilot, Cursor, or another agent with no adapter, do not send + ([02](02-ideal-customer-profile.md#disqualify-do-not-sell-the-pilot)). +- **No compliance claims.** Never write "compliant," "certified," "audit-ready," or + "satisfies ." Write "evidence your auditors can check." +- **No invented numbers** about their team, and no performance claims. +- **One ask per message**: a 30-minute call. +- Follow applicable law and the recipient's stated contact preferences (for + example CAN-SPAM, GDPR/PECR, CASL). Include an opt-out line in cold email. Stop + after the second follow-up. +- Links to include, all public: the [30-second tamper demo](https://github.com/New1Direction/korg#30-second-quickstart), + the [browser Certificate verifier](https://new1direction.github.io/korg/web/seal.html), + and the [one-page offer](01-offer.md), sent as an attachment or PDF. + +--- + +## 1. Cold email — platform or DevEx lead + +**Subject:** What Claude Code did in {{COMPANY}}'s repos, verifiably + +Hi {{FIRST_NAME}}, + +I saw {{AGENT_SIGNAL}}. When Claude Code edits code that ships, the only record of +what it did is the transcript on that developer's laptop, and nobody downstream +can check it. + +We run a fixed-price, two-to-four-week pilot that installs Korg, an open-source +flight recorder for Claude Code. Each session becomes a hash-chained record of +prompts, tool calls, and results. Recognized secrets are redacted before anything +is written. Selected sessions become signed Certificates that a reviewer can +verify offline, in CI or in a browser tab that uploads nothing. Everything runs +on your machines, and nothing is hosted by us. + +Here is a 30-second demo of a one-character edit being caught: +https://github.com/New1Direction/korg#30-second-quickstart + +Would a 30-minute call to see whether it fits {{COMPANY}}'s setup be useful? + +{{SELLER_NAME}} + +*If this isn't relevant, reply "no" and I won't follow up.* + +--- + +## 2. Cold email — security engineering lead + +**Subject:** Agent tool calls at {{COMPANY}}: can you show what ran? + +Hi {{FIRST_NAME}}, + +{{AGENT_SIGNAL}} suggests Claude Code is running shell commands and editing code +at {{COMPANY}}. If one of those sessions leaked a credential or ran something +destructive, could you show exactly what happened, in a form someone else can +verify? + +Korg is an open-source recorder that does this for Claude Code: + +- Every tool call and result goes into a SHA-256 hash chain. Once a session is + sealed into a signed Certificate, edit, delete, or reorder one event and + independent verifiers (Rust, Python, JavaScript) name the exact break. +- Recognized secrets (provider keys, bearer tokens, JWTs, private keys, credentialed + URLs) are replaced before hashing. In the pilot we test this with planted canaries + in your own formats and report what is not covered. +- It is local only, with no hosted collector. You hold the signing key. + +We sell it as a fixed-price pilot with written acceptance criteria. We tell you +the limits before you sign (for example, live capture is Claude Code only, and a +signature proves a key, not a person). + +Open to a 30-minute call? + +{{SELLER_NAME}} + +*Not relevant? Reply "no" and I'll stop here.* + +--- + +## 3. Cold email — GRC or compliance owner + +**Subject:** Evidence for AI-assisted changes ahead of {{COMPANY}}'s next audit + +Hi {{FIRST_NAME}}, + +{{AUDIT_SIGNAL}}, and {{AGENT_SIGNAL}}. When auditors or enterprise customers ask +how AI-assisted code changes are logged and reviewed, the honest answer today +is usually "we trust the developer." + +We run a short, fixed-price pilot that gives your engineering team a verifiable +record of what Claude Code did. The records are hash-chained, have secrets +redacted, and are signed with a key you hold. Your reviewers can check them +without trusting us or the tool. In the Evidence Pack option, we work with you to +draft a matrix linking those records to the controls *you* select, for your +auditor to evaluate. + +To be clear, this is not a certification or an audit opinion. It produces evidence, +and it is open about what that evidence does and does not prove. + +Worth 30 minutes before {{TRIGGER}}? + +{{SELLER_NAME}} + +*If this isn't for you, reply "no" and I won't write again.* + +--- + +## 4. Cold email — team on Codex CLI and Claude Code + +Use only when there is evidence of **both** agents. + +**Subject:** One verifiable record format for Claude Code and Codex at {{COMPANY}} + +Hi {{FIRST_NAME}}, + +It looks like {{COMPANY}} uses both Claude Code and Codex CLI ({{AGENT_SIGNAL}}). +Korg records Claude Code sessions as tamper-evident, independently verifiable +ledgers today. Codex is earlier: Korg can translate a recorded Codex trace into the +same format, but it does not capture Codex live yet. + +Our pilot installs live capture for your Claude Code users and replays one of your +Codex traces, so you get a straight answer on both before you commit to +anything. It is fixed price, and it runs on your machines. + +30 minutes to see if it fits? + +{{SELLER_NAME}} + +*Reply "no" and I'll stop here.* + +--- + +## 5. LinkedIn connection note (≤ 300 characters) + +> Hi {{FIRST_NAME}}, I saw {{AGENT_SIGNAL}}. I help teams on Claude Code keep a +> tamper-evident, independently verifiable record of what the agent ran and +> changed (open source, runs locally). Happy to share the 30-second demo if useful. + +--- + +## 6. Follow-up 1 (3–4 business days later) + +**Subject:** Re: {{ORIGINAL_SUBJECT}} + +Hi {{FIRST_NAME}}, + +A quick way to judge whether this is real: open +https://new1direction.github.io/korg/web/seal.html and click "a real seal", then +"forged summary". The page re-derives the summary from the events and catches the +forgery. You can also edit any character of the Certificate in the text box and +verify again. It all runs in your browser. + +If a call isn't useful right now, no reply is needed. + +{{SELLER_NAME}} + +--- + +## 7. Follow-up 2 — last message (7 business days after follow-up 1) + +**Subject:** Closing the loop + +Hi {{FIRST_NAME}}, + +I won't keep writing. If agent audit trails come up later, for example in a +security questionnaire or a wider Claude Code rollout, the one-page offer is +attached and I'm at {{SELLER_EMAIL}}. + +{{SELLER_NAME}} + +--- + +## 8. Post-call recap + +**Subject:** {{COMPANY}} × Korg pilot: recap and next step + +Hi {{FIRST_NAME}}, + +Thanks for the time today. What I heard: + +- Goal: {{GOAL_IN_THEIR_WORDS}} +- Agents and setup: {{AGENTS_AND_SETUP}} +- Timing driver: {{TRIGGER}} +- Fit concerns we discussed: {{CONCERNS}} + +Suggested tier: **{{TIER}}** ({{PRICE}}, {{DURATION}}). Scope, exclusions, and +acceptance criteria are attached, along with our security and data-handling terms +for your security reviewer. + +Next step: the attached technical discovery questionnaire. Within two business +days of your answers we will confirm the pilot or tell you plainly that Korg is +not a fit, before any invoice. + +{{SELLER_NAME}} + +--- + +## Objection replies + +**"Are you SOC 2 certified?" / "Will this make us compliant?"** +> No, and we won't claim that. Korg is open-source tooling, and the pilot produces +> evidence (verifiable records of agent activity) that you and your auditors can +> evaluate. Whether it meets a given control is your auditors' call. In Evidence +> Pack we help you draft that mapping for them to review. + +**"We already have logs."** +> Logs are useful, but whoever controls a log can edit it, and a reviewer has to +> trust it. Korg's records are hash-chained, and once a session is sealed into a +> signed Certificate that leaves the developer's machine, any later edit is caught +> by verifiers you run yourself. The Certificate also binds the summary a reviewer +> reads to the underlying events. + +**"Can't the developer (or the agent) just rewrite the whole chain?"** +> Before the session is sealed, yes. The agent runs as the developer's user, so it +> could too. A local unkeyed chain is tamper-evident only +> relative to a tip someone else holds. Sealing a session into a Certificate fixes +> its tip. Once that Certificate has left the machine (committed for CI, stored +> centrally, or anchored by its hash to a public commit), any later rewrite is +> caught. The +> window between capture and sealing is real, so the pilot measures it and the +> runbook decides who seals and when. It's spelled out in our security terms. + +**"We use Cursor / Copilot."** +> Korg doesn't capture those today, so the pilot isn't a fit, and we'd rather tell +> you now. If Claude Code is in your plans, we're happy to talk then. + +**"Why pay for something open source?"** +> You're paying for a working installation on your machines, drills run against +> your own sessions, measured coverage and overhead, and a report your security and +> GRC owners can act on, delivered in a fixed time with written acceptance criteria. +> You keep everything, with no license fee. diff --git a/sales/flight-recorder-pilot/CLAIMS.md b/sales/flight-recorder-pilot/CLAIMS.md new file mode 100644 index 0000000..e967d6e --- /dev/null +++ b/sales/flight-recorder-pilot/CLAIMS.md @@ -0,0 +1,132 @@ +# Claims and evidence + +Every technical statement in this kit must appear in this file with the public +source that backs it. If a claim is not listed here, do not make it. + +**Baseline:** `main` at +[`781bc41`](https://github.com/New1Direction/korg/commit/781bc414372d8f15a612160cc4844e08767bfbe5) +(korg-ledger@v1 revision 1.1). Redaction (`korg-redact@v1`), the lint commands, +`rechain-redacted`, `--require-redacted`, and causal-link checking of nested +journals landed in that commit after release +[v0.2.0](https://github.com/New1Direction/korg/releases/tag/v0.2.0), and are +listed as *Unreleased* in the [changelog](../../CHANGELOG.md). **Every pilot pins +a commit at or after `781bc41`, never the v0.2.0 tag.** Tell the customer that +this code is recent. + +## Claims you may make + +| # | Claim | Evidence | +|---|---|---| +| C1 | Claude Code sessions are captured through `PostToolUse`, `Stop`, and `SubagentStop` hooks into one ledger per session at `~/.korg/sessions/.jsonl`. The agent does not need to be instructed to log anything. | [`adapters/claude-code/README.md`](../../adapters/claude-code/README.md#what-it-produces), [`hook.py`](../../adapters/claude-code/src/claude_code_adapter/hook.py), [`claude_settings.py`](../../adapters/korg-setup/src/korg_setup/claude_settings.py) | +| C2 | The hook catches its own errors and always exits 0, so a capture failure does not fail the Claude Code session. It runs synchronously, so it does add time (see L12). | [`hook.py`](../../adapters/claude-code/src/claude_code_adapter/hook.py) module docstring | +| C3 | Historical Claude Code sessions already on disk can be backfilled into the same verifiable per-session format with `korg-backfill`, which can be limited to one project directory with `--projects-dir`. | [`adapters/claude-code/README.md`](../../adapters/claude-code/README.md#one-shot-backfill-of-history), [`backfill_cli.py`](../../adapters/claude-code/src/claude_code_adapter/backfill_cli.py) | +| C4 | Each ledger is a SHA-256 hash chain (`korg-ledger@v1`). Given a trusted tip, any edit, deletion, insertion, or reorder is detected and localized to a `seq_id`. The format also supports HMAC-keyed chains, which cannot be forged without the key; the Claude Code hook does not use them today. | [`spec/korg-ledger-v1/README.md`](../../spec/korg-ledger-v1/README.md), [`SPEC.md`](../../spec/korg-ledger-v1/SPEC.md) §3–5 | +| C5 | Causal links (`triggered_by`) form a checked DAG: prompt → model turn → tool call. Forward, dangling, and malformed links fail verification. | [`SPEC.md`](../../spec/korg-ledger-v1/SPEC.md) §9 | +| C6 | There are three independent verifier implementations (Rust, Python, JavaScript) that pass one shared conformance vector set and are differentially fuzzed against each other, with 0 divergences reported. | [`spec/korg-ledger-v1/README.md`](../../spec/korg-ledger-v1/README.md#conformant-implementations), [`CHANGELOG.md`](../../CHANGELOG.md) | +| C7 | Zero-install browser verifiers check a file locally in the page and do not upload it. The pages load web fonts from Google Fonts. | [Ledger verifier](https://new1direction.github.io/korg/web/index.html), [Certificate verifier](https://new1direction.github.io/korg/web/seal.html), [`seal.html`](../../spec/korg-ledger-v1/web/seal.html) | +| C8 | Secrets matching `korg-redact@v1` rules (sensitive key names, bearer tokens, provider/GitHub/Slack/AWS/Google keys, JWTs, PEM private keys, URL credentials, `NAME_TOKEN=…` assignments) are replaced with `[REDACTED:]` *before* hashing. This is on by default in `LedgerWriter`, which the Claude Code hook uses. | [`REDACTION.md`](../../spec/korg-ledger-v1/REDACTION.md), [`writer.py`](../../adapters/korg-ledger-py/src/korg_ledger/writer.py), [`canonical_emit.py`](../../adapters/claude-code/src/claude_code_adapter/canonical_emit.py) | +| C9 | `python -m korg_ledger lint` (ledgers) and `korg-verify --require-redacted` (ledgers and Certificates) flag any persisted secret the rules recognize. `python -m korg_ledger rechain-redacted` migrates a leaked journal to a new, clean chain. | [`REDACTION.md`](../../spec/korg-ledger-v1/REDACTION.md), [`adapters/korg-ledger-py/README.md`](../../adapters/korg-ledger-py/README.md), [`crates/korg-verify/README.md`](../../crates/korg-verify/README.md) | +| C10 | A `korgcert@v1` Certificate embeds a session's full event chain, a summary re-derived from those events (agents, tool counts, file paths from file-tool arguments, seq range), and an Ed25519 issuer seal. Verifiers reject a summary that disagrees with the events, a missing seal, and (when pinned) the wrong issuer key. | [`KORGCERT.md`](../../spec/korg-ledger-v1/KORGCERT.md) §1–5, [`adapters/korg-seal/README.md`](../../adapters/korg-seal/README.md) | +| C11 | `korg-seal mint` refuses to seal a chain that does not verify. | [`adapters/korg-seal/README.md`](../../adapters/korg-seal/README.md#use) | +| C12 | A Certificate can be anchored to a public GitHub commit that adds a line containing the anchored hash. `korg-seal resolve` fetches the commit and confirms it introduced the hash. That shows the tip was published in that commit. The commit date is self-asserted by git, so the dependable bound is "before any third party fetched or mirrored that commit." | [`adapters/korg-seal/README.md`](../../adapters/korg-seal/README.md#trusted-time--anchor-to-a-public-commit-then-resolve), [`resolve.py`](../../adapters/korg-seal/src/korg_seal/resolve.py), [`SPEC.md`](../../spec/korg-ledger-v1/SPEC.md) §8.2 | +| C13 | A composite GitHub Action verifies Certificates and ledgers in CI (the verification itself makes no network calls), optionally pins the issuer key, writes a job summary, optionally posts a PR comment, and fails the job on any tampered or unverifiable file. | [`.github/actions/verify-korgcert/action.yml`](../../.github/actions/verify-korgcert/action.yml), [`korgcert-demo.yml`](../../.github/workflows/korgcert-demo.yml) | +| C14 | The same ledger format ingests traces from OpenAI Codex CLI (WebSocket frames) and Grok Heavy (NDJSON) through library adapters with tests. | [`README.md`](../../README.md#validated-across-three-vendors-n3), [`adapters/codex-ws/README.md`](../../adapters/codex-ws/README.md), [`adapters/grok-heavy/README.md`](../../adapters/grok-heavy/README.md) | +| C15 | Korg is open source under MIT or Apache-2.0. There is no license fee. | [`LICENSE`](../../LICENSE), [`LICENSE-APACHE`](../../LICENSE-APACHE) | + +## Which verifier checks what + +"Independent" means a different implementation. The Node.js CLI and the browser +pages run the same `verify.mjs`, so together they count as **one** (JavaScript). + +| Check | Rust | Python | JavaScript (Node CLI or browser) | +|---|---|---|---| +| Ledger chain + causal DAG | `korg-verify ` | `python -m korg_ledger lint ` | `node spec/korg-ledger-v1/js/bin.mjs ` or the [ledger page](https://new1direction.github.io/korg/web/index.html) | +| Certificate (chain, summary, seal, pinned key) | `korg-verify --pubkey ` | `korg-seal verify --pin ` | `node spec/korg-ledger-v1/js/bin.mjs --pubkey ` or the [Certificate page](https://new1direction.github.io/korg/web/seal.html) | +| Redaction lint | `korg-verify --require-redacted` (ledgers and Certificates) | `python -m korg_ledger lint` on a ledger. It misreads a Certificate file as a single event, so for a Certificate run it on the extracted events: `jq -c '.events[]' cert.json > events.jsonl` | none | + +`python -m korg_ledger lint` reports chain, DAG, and redaction problems together. +When comparing verdicts across verifiers, compare chain and DAG results only; a +redaction finding is a separate check. + +## Limits to disclose + +Say these before the customer finds them. + +| # | Limit | Evidence | +|---|---|---| +| L1 | **Live capture covers Claude Code only.** The Codex CLI and Grok Heavy adapters are libraries that translate recorded traces. They have no CLI, and their documented output path posts to `korg-server`, which the pilot does not deploy. Recording Codex means intercepting its WebSocket traffic (for example with mitmproxy), which also captures credentials. The pilot therefore treats Codex as a feasibility replay that needs a short glue script. No adapter exists for Copilot, Cursor, Windsurf, or Gemini CLI. | [`adapters/codex-ws/README.md`](../../adapters/codex-ws/README.md) | +| L2 | **An unkeyed chain is tamper-evident, not tamper-proof.** Whoever controls the ledger file can rewrite and rehash the whole chain. That includes the agent itself, whose shell tool runs as the same OS user. Detection needs a trusted tip held elsewhere: a sealed Certificate that has left the machine, an external anchor, or an HMAC key the writer does not hold. Anything rewritten *before* the tip is fixed goes undetected, so the time between capture and sealing is a real exposure. | [`SPEC.md`](../../spec/korg-ledger-v1/SPEC.md) §8.2 honest limits | +| L3 | **Signatures prove a key, not a person or an organization.** The relying party pins the issuer public key. There is no hosted key registry and **no revocation**: a leaked key's past seals stay valid for anyone who still pins it. | [`KORGCERT.md`](../../spec/korg-ledger-v1/KORGCERT.md) §1 and "No revocation" | +| L4 | **No trusted timestamp.** `issued_at` and `anchored_at` are local clocks, and a git commit date is self-asserted. Public anchoring needs a public GitHub repository, because `resolve` uses the unauthenticated GitHub API. The top-level README lists a "live network anchoring resolver (trusted-time witness)" as not shipped; `korg-seal resolve` exists but gives only the weaker bound in C12. | [`KORGCERT.md`](../../spec/korg-ledger-v1/KORGCERT.md) §1, [`resolve.py`](../../adapters/korg-seal/src/korg_seal/resolve.py), [`README.md`](../../README.md#status) | +| L5 | **A Certificate proves a faithful record, not good work.** The `claim` field is free prose that the issuer signs but no machine checks. A Certificate is also not bound to a git commit or PR diff. | [`KORGCERT.md`](../../spec/korg-ledger-v1/KORGCERT.md) §1 | +| L6 | **Redaction is rule-based, not DLP.** It catches the listed patterns and sensitive key names. Customer-specific secret formats, personal data, and proprietary code are recorded as-is. | [`REDACTION.md`](../../spec/korg-ledger-v1/REDACTION.md) §3 | +| L7 | **The `stream-json` adapter writes large payloads to `.korg/blobs/` without redaction.** The pilot does not deploy it. | [`adapters/stream-json/README.md`](../../adapters/stream-json/README.md) | +| L8 | **Local, single-user trust boundary.** `korg-server` and `mcp_server.py` must not run on a shared or untrusted network. The pilot does not deploy them. | [`README.md`](../../README.md#what-korg-does) trust-boundary warning | +| L9 | **Capture records what the Claude Code transcript shows.** That means prompts, model turns, tool calls, and results. It does not see actions outside Claude Code, and it does not block or approve actions. | [`hook.py`](../../adapters/claude-code/src/claude_code_adapter/hook.py), [`adapters/claude-code/README.md`](../../adapters/claude-code/README.md#causal-mapping) | +| L10 | **Packaging is source-based, and the published packages are stale.** `korg-verify` 0.1.0 on crates.io and `@korgg/ledger-verify` 0.1.0 on npm (both June 2026) predate Certificates and redaction, so the pilot does not use them. Nothing is on PyPI. `claude-code-adapter` declares a dependency on `korg-ledger-py`, a name that was not registered on PyPI as of 2026-10-13. To avoid dependency confusion, install from a local checkout with `--no-deps`. The release ships `korg` binaries only, so `korg-verify` is built from source. | [`README.md`](../../README.md#status), [`adapters/claude-code/pyproject.toml`](../../adapters/claude-code/pyproject.toml), [v0.2.0 release](https://github.com/New1Direction/korg/releases/tag/v0.2.0) | +| L11 | **Platform.** The hook uses POSIX file locks and CI runs on Linux. macOS and Linux workstations are in scope; Windows is not validated. | [`hook.py`](../../adapters/claude-code/src/claude_code_adapter/hook.py) (`fcntl`), [`ci.yml`](../../.github/workflows/ci.yml) | +| L12 | **Hook overhead is unmeasured.** The hook reparses the whole session transcript on every firing, synchronously, so its cost grows with session length. The pilot measures it rather than promising a number. | [`hook.py`](../../adapters/claude-code/src/claude_code_adapter/hook.py) | +| L13 | **Capture fidelity.** Tool results over 8,000 characters are truncated. Transcript wall-clock timestamps are not carried into the ledger, which keeps causal order but not absolute timing. Subagent (sidechain) events are flattened into the parent session. Events that fail a causality or redaction check are dropped rather than written, which shows up as a coverage difference. | [`adapters/claude-code/README.md`](../../adapters/claude-code/README.md#known-limitations), [`canonical_emit.py`](../../adapters/claude-code/src/claude_code_adapter/canonical_emit.py) | +| L14 | **The summary's `files` list is not "every file changed."** It lists `file_path`/`path` arguments of tool calls, so files changed through shell commands (`sed -i`, `rm`, `git mv`) are missing and files that were only read are included. | [`KORGCERT.md`](../../spec/korg-ledger-v1/KORGCERT.md) §4 | +| L15 | **Certificates contain the whole session.** A Certificate embeds every event, so it is as sensitive as the ledger. Never publish one to anchor it; publish only the hash. | [`KORGCERT.md`](../../spec/korg-ledger-v1/KORGCERT.md) §2 | +| L16 | **Hook scope is set by where it is registered.** A hook in the user-level `~/.claude/settings.json` records every Claude Code session on the machine, in every repository. The pilot registers it per pilot repository instead, in `.claude/settings.local.json`, which Claude Code reads for that project only. A hand-created copy of that file must be added to `.gitignore`. | [`claude_settings.py`](../../adapters/korg-setup/src/korg_setup/claude_settings.py) (user-level default); Claude Code [settings](https://code.claude.com/docs/en/settings) and [hooks](https://code.claude.com/docs/en/hooks) docs (project-local settings) | +| L17 | **`korg-setup` is not used in the pilot.** It requires `korg-recall-mcp` on the PATH (even for `--dry-run`), always registers the recall MCP server, and writes a backup of `~/.claude.json`, which holds Claude Code login state. The pilot registers the hook by hand. | [`setup.py`](../../adapters/korg-setup/src/korg_setup/setup.py), [`adapters/korg-setup/README.md`](../../adapters/korg-setup/README.md#safety) | + +## Questions prospects ask about the repository README + +- *"Your README says agents must be instructed to log, and that fully passive + capture is on the roadmap."* The README's wording there is broader than the + current state. The note sits in the MCP-sink section, and the roadmap item covers + agents in general. The Claude Code hook, documented in the + [claude-code adapter README](../../adapters/claude-code/README.md#what-it-produces) + and listed as shipped in the same Status section, needs no agent cooperation (C1). + Other agents still do, or have no capture path (L1). Say this plainly instead of + arguing about wording. +- *"The README says the anchoring resolver isn't shipped."* The trusted-time + witness isn't shipped. `korg-seal resolve` exists and gives the weaker, + publication-based bound in C12 (L4). +- *"The browser page offers a 'Gold Seal – verified' badge, and the CI action + comments 'Certificate verified'."* "Verified" there means the record passed + cryptographic checks. It is not a compliance mark, and the pilot does not use + badges in customer-facing material. + +## Claims you must not make + +- "Korg makes you SOC 2 / ISO 27001 / EU AI Act compliant," "certified," "audit-ready," or "approved by auditors." +- "Captures every coding agent," "fully passive for all agents," or support for any agent outside L1. +- "Tamper-proof" for an unkeyed chain, "trusted timestamp," "proves when," or "proves who wrote the code." +- "Without trusting the agent" for a session that has not been sealed yet (L2). +- "Lists every file the agent changed" (L14), or that a Certificate is tied to a specific commit or PR (L5). +- "Prevents" or "blocks" unsafe agent actions (this pilot records them). +- Hosted dashboards, transparency logs, key registries, revocation, SaaS, or any roadmap item as available. +- Any performance number not measured in the customer's own pilot. + +## Validation log + +On 2026-10-13, against `781bc41`, in a clean Linux sandbox: + +- The JS verifier reported `journal VALID — 6 events` on the + [sample session](../../spec/korg-ledger-v1/web/samples/session.jsonl). After one + line was edited it reported `seq 4: entry_hash mismatch` and exited 1. Deleting + an event and swapping two events were each reported as `prev_hash breaks the + chain` by both the JS verifier and `korg_ledger lint`. +- The [sample Certificate](../../spec/korg-ledger-v1/web/samples/korgcert.json) + verified as `korgcert VALID`. With one file removed from its summary, both JS and + `korg-seal verify` reported `summary does not match the events`. +- `python -m korg_ledger lint` on the sample Certificate file reported + `missing entry_hash`, confirming that it cannot read a Certificate directly. On + the Certificate's events extracted with `jq -c '.events[]'` it reported + `redaction-clean`. After a bearer token was planted in one event, it flagged + `unredacted bearer_token` and exited 1. +- JS and Python conformance suites: `PASS`. +- 265 tests passed across `claude-code`, `korg-seal`, `korg-setup`, and `korg-ledger-py`. +- End to end: a synthetic Claude Code transcript containing a bearer token was + fed to `korg-hook`. The resulting 5-event ledger contained `[REDACTED:bearer_token]` + and no raw token, and `korg_ledger lint` reported it chain-intact and + redaction-clean. `korg-seal mint` produced a Certificate that the JS verifier + accepted with the issuer key pinned and rejected with a different pinned key. + +Not run in that sandbox: the Rust `korg-verify` binary (no Rust toolchain was +available), a live Claude Code session, and the GitHub Action. Week 1 of each +pilot covers the first two on the customer's machines; the CI tiers cover the +action. diff --git a/sales/flight-recorder-pilot/README.md b/sales/flight-recorder-pilot/README.md new file mode 100644 index 0000000..ad74b89 --- /dev/null +++ b/sales/flight-recorder-pilot/README.md @@ -0,0 +1,81 @@ +# Korg Agent Flight-Recorder Pilot — sales kit + +A fixed-price, fixed-scope pilot that installs Korg's open-source flight recorder +for a team's coding agents, proves on the team's own sessions that the record is +complete enough to be useful and tamper-evident, and hands over an evidence pack +the team's security, GRC, or audit owners can inspect themselves. + +> **What this is not.** Korg is not a compliance certification, an audit opinion, +> or a legal assessment. The pilot produces *evidence* (verifiable records of what +> agents did) that a customer and its auditors may choose to use. Nothing in this +> kit says or implies that a customer becomes "compliant" or "certified" with any +> framework. + +This directory is sales material only. It does not change Korg's source, spec, or +release artifacts; every technical statement here is traced to public code and +docs in [CLAIMS.md](CLAIMS.md). + +## Pilot at a glance + +These are the canonical numbers. Every other document in this kit must match them. + +| | **Recorder** | **Recorder + CI Gate** | **Evidence Pack** | +|---|---|---|---| +| Fixed price (USD) | **$6,500** | **$14,500** | **$24,000** | +| Duration (after kickoff) | 2 weeks | 3 weeks | 4 weeks | +| Repositories | 1 | up to 2 | up to 3 | +| Pilot developers on Claude Code | up to 5 | up to 10 | up to 20 | +| Live capture | Claude Code | Claude Code | Claude Code | +| Certificates + pinned issuer key | ✓ | ✓ | ✓ | +| Tamper and redaction drills | ✓ | ✓ | ✓ | +| CI verification gate on pull requests | — | ✓ | ✓ | +| Public git-tip anchoring (opt-in) | — | ✓ | ✓ | +| Second-agent feasibility (Codex CLI trace replay) | — | ✓ | ✓ | +| Control-evidence mapping workshop | — | — | ✓ | +| Post-acceptance async support | 14 days | 30 days | 30 days | + +Payment: 50% at signature, 50% on acceptance. Details in [08-pricing.md](08-pricing.md). + +## The kit + +| # | Document | Use it to | +|---|---|---| +| 01 | [Service offer](01-offer.md) | Send as the one-page offer after a first call | +| 02 | [Ideal customer profile](02-ideal-customer-profile.md) | Qualify or disqualify a prospect | +| 03 | [Scope and exclusions](03-scope-and-exclusions.md) | Attach to the SOW | +| 04 | [Deliverables](04-deliverables.md) | Attach to the SOW | +| 05 | [Technical discovery questionnaire](05-discovery-questionnaire.md) | Send after the prospect agrees to scope a pilot | +| 06 | [Security and data-handling terms](06-security-and-data-handling.md) | Send to the prospect's security reviewer | +| 07 | [Pilot timeline](07-timeline.md) | Plan kickoff and the readout | +| 08 | [Pricing options](08-pricing.md) | Quote | +| 09 | [Acceptance criteria](09-acceptance-criteria.md) | Attach to the SOW; run at the end of the pilot | +| 10 | [Sample report outline](10-sample-report-outline.md) | Show what the customer gets | +| 11 | [Outreach templates](11-outreach-templates.md) | Personalize first-touch and follow-up messages | +| — | [Claims and evidence](CLAIMS.md) | Check a technical statement before you make it | + +## Rules for anyone selling this + +1. **Claude Code is the only live capture path.** Codex CLI and other agents are + offered only as a *feasibility replay* of a sample trace, never as production + capture. Copilot, Cursor, Windsurf, and Gemini CLI have no Korg adapter. +2. **Say "evidence for," never "compliant with."** No certification language, no + "audit-ready" guarantees, no badges. "Certificate" is the name of Korg's file + format (`korgcert@v1`), not a compliance certificate. Say so the first time + you use the word with a prospect. +3. **State the trust limits up front.** An unkeyed local chain shows tampering + only relative to a tip someone trusts. A sealed Certificate that has left the + developer's machine fixes the tip from that moment. A rewrite *before* sealing, + including one by the agent itself, is not detectable. Neither sealing nor public + anchoring proves a real-world identity or a trusted clock time + ([CLAIMS.md](CLAIMS.md#limits-to-disclose)). +4. **Ledgers and Certificates contain source code and command output.** Treat + both as confidential source code, and never publish a Certificate + ([06](06-security-and-data-handling.md)). +5. **Do not promise unshipped roadmap items** (hosted dashboard, transparency + log, fully passive capture of every agent, up-to-date crates.io/npm/PyPI + packages). The crates.io and npm verifier packages are stale 0.1.0 releases; + never point a prospect at them. +6. **Pin a Korg commit at or after `781bc41`**, never the v0.2.0 tag, which + predates redaction ([CLAIMS.md](CLAIMS.md)). +7. **Re-check [CLAIMS.md](CLAIMS.md) against `main`** before each quote. The + product moves quickly; the kit must not get ahead of it.