BOTTLENECK — Issue 01 (SecureGit Edition) Full editorial manuscript & page-by-page layout brief Prepared for handoff to Claude Design (Adobe InDesign / Express) Companion file: BOTTLENECK-Issue01-SECUREGIT-ArtDirection.md --- PUBLICATION FACTS | Field | Value | |---|---| | Title | BOTTLENECK | | Standfirst | The magazine for engineers becoming AI engineers. | | Issue | No. 01 — THE UNTRUSTED CLONE | | Cover subject | SecureGit — zero-trust git, guarded commits, chain-of-custody evidence | | Series | A limited series. One issue per system on the board. | | Publisher | ArmyknifeLabs | | Extent | 64 pages, self-cover | | Trim | 8.5 × 11 in (US Letter), digital-first, print-safe | | Voice | Senior engineer, plainspoken. Declarative. Opinionated. No hype vocabulary. | | Primary job | Adoption. A reader should finish page 23 already using it, and finish page 61 able to roll it out to a team. | | Disclosure | Sanitized architecture + anonymized figures. Safe for public distribution. | The editorial contract for this issue This is a magazine, not a brochure. The difference is enforced by three rules: 1. Every feature carries a maturity marker. SHIPPED, DESIGNED, or PLANNED. No exceptions, no soft language, no "coming soon" used to imply "nearly here." A reader who installs the tool must find exactly what this issue promised. 2. Every friction point is named before the reader hits it. Adoption dies on unpleasant surprises, not on missing features. We publish the surprises. 3. The tool is described as it behaves, not as it is positioned. Where SecureGit is worse than an alternative, we say so and say when to use the alternative. House style (enforce throughout) - Banned words: unlock, game-changing, revolutionize, seamless, leverage (verb), supercharge, 10x, journey, empower, cutting-edge, effortless, simply. - "Simply" is banned specifically because it is the word that makes a struggling reader feel stupid. If a step is simple, it will read as simple without being told. - Sentences average under 18 words. Paragraphs cap at four sentences. - Second person throughout Parts I and V (the reader is doing something). Third person in Parts II–IV (the reader is understanding something). - Every command shown is copy-pasteable and complete. No ... inside a command a reader is meant to run. - Anonymized values only. No real hostnames, IPs, addresses, filing numbers, or credential-shaped strings. --- PAGE 1 — COVER Masthead BOTTLENECK Issue line (small caps, under masthead rule) NO. 01 · THE UNTRUSTED CLONE · A LIMITED SERIES Cover line (dominant, stacked, 4 lines, flush left) git clone RUNS SOMEBODY ELSE'S CODE. Sub-cover line You knew that. You did it anyway, this week, probably twice. A field guide to SecureGit — and to git that can prove what happened. Cover teasers (lower third, hairline rules between) DAY ONE — installed and scanning in ten minutes ACQUIRE, NOT CLONE — why archive-first defeats hooks TWELVE SCANNERS — the built-in set, and the plugin ladder THE GUARDED COMMIT — a gate that does not slow you down RECEIPTS — cryptographic chain of custody for every push SARIF + GITLAB SAST — reports that upload where your dashboards already live BASELINES — adopting on legacy code without failing every build AUDIT LOG — hash-chained, tamper-evident, SIEM-ready HANDLES, NOT VALUES — giving agents credentials they never see THE 30-DAY ROLLOUT — solo, then team, then org TWELVE OBJECTIONS — answered honestly, including the ones we lose Bottom rule (reversed out of signal color) PLUS: THE MATURITY TABLE — every feature marked SHIPPED, DESIGNED, OR PLANNED · CURRENT VERSION 0.12.16 Cover art direction: a wide field of fine parallel rules — the "flow" — running left to right, interrupted at roughly 60% width by a single vertical gate. Rules that pass through the gate continue in ink; a small number are turned back at the gate and rendered in signal orange, curling away. No locks. No shields. No hooded figures. No padlock iconography of any kind. The gate is a hairline, not a wall — the whole argument of the issue is that the gate is thin. --- PAGE 2 — MASTHEAD & HOW TO READ THIS ISSUE BOTTLENECK The magazine for engineers becoming AI engineers. Issue 01 · The Untrusted Clone Published by ArmyknifeLabs. About this issue. Most tooling magazines are written by people who want you to be impressed. This one is written by the people who build the tool, for people who are deciding whether to type one command. Being impressed is not the goal. Typing the command is. How to read this issue If you have ten minutes: page 11. That is the quickstart. It ends with you having scanned a real repository. Everything else in this issue is optional after that. If you have an evening: Part I, pages 10–23. That is Day One in full — install, first acquire, first scan, reading findings, aliases, the pre-commit hook, and a straight answer on speed. You will finish it with SecureGit in your daily workflow. If you are evaluating this for a team: start at page 56 (the twelve objections), then page 53 (the 30-day rollout), then come back to Part II for the mental model. You need the objections first because your team will raise them before you finish your first sentence. If you are in a regulated environment: Parts III and IV, pages 38–51. SBOM anchoring, CVE state over time, license posture, and the credential boundary. Then the maturity table on page 63, because some of what you need is DESIGNED and not yet SHIPPED, and you should know which before you plan around it. The maturity markers Every capability in this issue is marked. Here is exactly what the three words mean, and we hold ourselves to them: SHIPPED — in a released build. You can install it today and use it. If you cannot, that is a bug and we want the report. DESIGNED — the architecture is decided and written down in an accepted design record, and implementation is partial or scheduled. It is real engineering intent, not a wish. It is not something you can run. PLANNED — identified, scoped, not yet designed in detail. Directional only. Do not build a procurement plan on a PLANNED row. If a page describes something and you cannot find the marker, treat it as PLANNED and write to us, because we made a mistake. Corrections run at the front of the next issue, at the same size as the original claim. --- PAGE 3 — CONTENTS ISSUE 01 · THE UNTRUSTED CLONE FRONT 04 — Editor's Letter: The Repository Is The Attack Surface 06 — Ninety Seconds: what actually happens when you clone 08 — What SecureGit Is, And What It Is Not PART I · DAY ONE 10 — Section opener 11 — The Ten-Minute Quickstart 12 — Install, and your first acquire 14 — Your first scan, and how to read a finding 16 — Making it feel like git: aliases and muscle memory 18 — The pre-commit hook: your first guardrail 20 — "Will this slow me down?" — the honest performance page 22 — Day One checklist, and what to do when it goes wrong PART II · THE MENTAL MODEL 24 — Section opener 25 — Acquire, not clone: why archive-first defeats hooks 28 — Scan: twelve built-in scanners and the plugin ladder 31 — The guarded commit: staged scanning without the friction 34 — The chain of custody: receipts, tiers, and the push gate PART III · SUPPLY CHAIN & GOVERNANCE 38 — Section opener 39 — SBOM, OSV, and the number that matters more than zero 42 — Lock files, licenses, and what changed when 44 — SARIF, GitLab SAST, and baselines: reports that upload where your dashboards live 45 — The audit log & compliance report: hash-chained evidence, OWASP + NIST SSDF mapping PART IV · SECRETS & AGENTS 46 — Section opener 47 — Handles, not values: the secret broker 49 — Server discovery and the credential boundary 50 — SecureGit for agents: the MCP surface PART V · ADOPTION 52 — Section opener 53 — The 30-day rollout: solo → team → org 56 — Twelve objections, answered honestly 58 — CI/CD integration that people do not disable 60 — Troubleshooting and the false-positive playbook BACK 62 — Command reference card 63 — The maturity table · Glossary 64 — Back cover --- PAGES 4–5 — EDITOR'S LETTER The Repository Is The Attack Surface Deck: You have spent your career securing what you deploy. The thing you never secured is the moment code arrives on your machine — and that moment now happens dozens of times a week, increasingly without you watching. --- Here is a thing every engineer knows and almost nobody acts on. git clone is not a download. It is a download plus a filesystem write plus, depending on what is in the archive and what you do next, code execution. Hooks. Submodule configuration. Filter drivers. Path handling quirks that have produced real CVEs in real git releases more than once. The repository is not data that you then choose to run. It is a bundle of data and executable configuration that you have invited onto your machine, inside your home directory, with your permissions. You know this. So does everyone. And then a colleague posts a link, and you clone it, because the alternative is not cloning it, and that is not a real alternative. The reason this became urgent rather than merely true is that the volume changed. Two years ago you cloned a handful of repositories a month, and you had usually heard of them. Now an agent working on your behalf pulls down a dependency you have not evaluated, to check whether its API does what a search result claimed. It does that at three in the morning while you are asleep, using your credentials, on your machine. The judgment step that used to sit between "I found this repository" and "it is now on my disk" has been compressed to nothing, and in many workflows removed entirely. That is the bottleneck this issue is about. Not "can I get the code" — that was solved decades ago. Can I get the code without the act of getting it being the vulnerability, and can I prove afterward what arrived and what I did with it. --- PULL QUOTE (page 4, outer column, signal) git clone is not a download. It is a download that has been granted permission to run. --- There is a second half to this, and it is the half that turns a security tool into an engineering tool. Once you accept that code arrival is an event worth controlling, you notice that code departure is too. A push is the first moment your work crosses onto shared infrastructure. It is the moment where "I wrote this" becomes "we shipped this." And in almost every organization, that moment carries no durable proof of anything: not who wrote which lines, not which of those lines came from a human versus an agent, not whether any scanner ever looked at it, not what the dependency posture was at the time. Six months later somebody asks. They ask because of an audit, or an incident, or a customer questionnaire, or a diligence process. And the honest answer is that you have git history, which tells you what changed and who the commit claims to be from, and nothing else. Git history is a record of assertions, not a record of evidence. It was never designed to be otherwise — Linus was solving a different problem, and solving it very well. SecureGit is one answer to both halves. It puts a thin gate on arrival, a thin gate on departure, and a cryptographic receipt on both. That is the whole idea, and the rest of this issue is about whether the gates are thin enough that you will actually keep them. --- PULL QUOTE (page 5, inset, boxed) Git history is a record of assertions, not a record of evidence. That was the right design for 2005. It is an expensive gap in 2026. --- Now the part where I tell you what this is going to cost you, because adoption articles that skip this are the reason engineers distrust adoption articles. It will cost you a new verb. You will type acquire instead of clone for untrusted repositories. That is a habit change, and habit changes fail unless you make them cheap. Page 16 is entirely about making it cheap. It will cost you seconds, and occasionally a minute. Scanning is not free. On a normal working repository it is fast enough that you will stop noticing. On a very large repository it is not, and page 20 gives you real numbers rather than reassurance. It will cost you some false positives. Every scanner produces them. A scanner that claims otherwise is either lying or not looking hard. Page 60 is a playbook for driving them down, because a tool that cries wolf gets disabled in week two, and a disabled tool has negative value — it provides the feeling of security with none of it. And it will cost you a conversation with your team, which is the expensive part. Page 56 gives you the twelve objections you will hear, with honest answers, including the three cases where the honest answer is "you are right, do not use this for that." What you get for it: code that arrives without executing, commits that cannot silently ship a secret, pushes that carry proof, and — the part that surprises people — a genuine answer to the question "what did we know about our supply chain in March," which is a question that currently ends most enterprise sales conversations in an uncomfortable silence. Start at page 11. It takes ten minutes and it ends with you having scanned something real. — The Editors --- PAGES 6–7 — NINETY SECONDS (INFOGRAPHIC SPREAD) Spread headline (spans gutter): WHAT ACTUALLY HAPPENS Deck: Two timelines, same repository. The top is git clone. The bottom is securegit acquire. Read them against each other. Panel A (left page, upper) — TIMELINE ONE: git clone Format: a horizontal timeline, left to right, with events as ticks above the line and trust state as a colored band below it. The band starts neutral and turns signal-orange at the first execution point, staying orange to the end. | Moment | What happens | Your exposure | |---|---|---| | t+0 | Network fetch begins | None yet | | t+2s | Objects written into .git | Disk write, your permissions | | t+3s | Hook scripts land in .git/hooks | Dormant executables now on disk | | t+3s | .gitmodules, .gitattributes, config land | Filter and submodule directives, unread | | t+4s | Working tree checkout | Paths written per attacker-influenced names | | t+4s | Clone reports success | You believe you have data. You have data and configuration. | | t+30s | You cd in and run anything git-adjacent | Hooks may execute. Filters may execute. | | t+45s | You open the repo in an editor with extensions | Editor-level execution surface | Annotation (signal, pointing at t+3s): Nothing has run yet. That is the entire window in which a decision is still cheap. git clone gives you no place to stand inside it. Panel B (left page, lower) — TIMELINE TWO: securegit acquire | Moment | What happens | Your exposure | |---|---|---| | t+0 | Fetched as an archive, not as a live repo | Inert bytes | | t+2s | Archive extracted to a staging path | Files on disk, no git configuration active | | t+2s | Hooks stripped | Dormant executables removed, not merely ignored | | t+3s | Scanners run across the tree | Findings collected | | t+4s | A sanitization report is written alongside | You have something to read | | t+5s | Converted into a normal git repository | Now it is a repo — after inspection | | t+5s | SHIPPED — a chain receipt records the acquisition | Provenance from moment zero | Annotation: The order is the product. Fetch, strip, inspect, then confer git-ness. git clone confers git-ness first and inspects never. Panel C (right page, full) — THE THREE THINGS PEOPLE GET WRONG Format: three tall cards, each with a myth in condensed caps, a correction in serif body, and a one-line takeaway in mono. MYTH 1 · "I only clone repos I trust." You clone repos your dependencies trust, which is a different set and a much larger one. You also clone repos an agent selected on your behalf from a search result. The trusted-source model assumes a human evaluated the source. Increasingly, none did. → The question is not "do I trust this" but "did anyone actually look." MYTH 2 · "My scanner catches this." Most scanning runs in CI, which is after the clone, on a machine that is not yours, looking at the tree rather than the repository metadata. The hooks that concern us are in .git, which most scanners exclude by default and which CI usually does not receive. → Scan the .git directory. Most tools do not, by default. Check yours. MYTH 3 · "This is theoretical." Hook execution and path-handling behavior in git have produced real, patched CVEs on multiple occasions. The mitigation is always "upgrade git," which works until the next one, and which does nothing about the window between disclosure and your fleet actually upgrading. → Defense in depth exists because point fixes arrive late and unevenly. Foot callout (right page, reversed): The honest framing SecureGit does not make untrusted code safe. Nothing does. It makes the acquisition of untrusted code non-executing, and it gives you a place to stand — a moment where the code is on your disk, inert, and you can look at it before it becomes a live repository. That moment did not previously exist. That is the entire contribution. Everything else in this issue is built on it. --- PAGES 8–9 — WHAT SECUREGIT IS, AND WHAT IT IS NOT Headline: THE ONE-PAGE MENTAL MODEL Deck: Before any command, this. Five minutes here saves an hour of confusion later. --- The one sentence SecureGit is a git wrapper that puts a gate on the two moments code crosses a trust boundary — arrival and departure — and writes a signed receipt for each crossing. Everything else is elaboration. If you remember one thing, remember: arrival, departure, receipt. The four layers Think of it as four layers stacked, each usable without the ones above it. You can adopt one layer and stop. Most people should, at first. LAYER 1 · ACQUISITION SHIPPED Fetch untrusted code without executing it. securegit acquire replaces git clone for anything you did not write. Archive-first (ZIP-with-history by default; zip-only and bare-checkout also available), hooks stripped, twelve scanners run, then converted to a normal git repo. Adopt this alone and you have already gotten most of the day-one value. LAYER 2 · SCANNING SHIPPED Twelve built-in Rust scanners — secrets, patterns, entropy, binary, encoding (Trojan Source), supply chain, CI/CD, container, IaC, deserialization, dangerous files, git internals — plus a plugin system that wraps tools you already use. Run it on a path, on staged changes, on a diff, or in CI. Outputs pretty, JSON, SARIF 2.1.0, or GitLab SAST v15. --write-baseline lets you adopt on a legacy codebase without failing every build. Adopt this second. It is the layer that changes your commit habits. LAYER 3 · CHAIN OF CUSTODY & GOVERNANCE SHIPPED (core, audit log, layered policy) / DESIGNED (offline chain, batch lookup) Every trust-boundary operation emits a cryptographically signed receipt. Push can be gated on whether the commits in range have receipts. Blame can show provenance per line. A separate hash-chained audit log captures every security-relevant event (scan, block, hook, baseline write, credential change) and exports as JSONL or CEF for SIEM ingest. Layered configuration (/etc/securegit → user → repo → env) with [policy] minfailon, lockedkeys, and auditrequired gives security teams a governance surface developers can tighten but not weaken. Adopt this when you need to prove things to someone who was not there. Two of its three pieces (audit log, policy) work without any signing infrastructure. LAYER 4 · SUPPLY-CHAIN PROVENANCE SHIPPED (anchoring, SBOM, compliance report) / DESIGNED (parts) SBOM anchoring, CVE state at a point in time, license posture, lock-file change records — all attached to the same chain. Releases ship a CycloneDX SBOM, SHA256SUMS, and a Sigstore keyless (cosign) signature. securegit compliance report maps findings to OWASP Top 10 (2021) via CWE and summarizes NIST SSDF v1.1 practice coverage — markdown or JSON, straight into a review packet. Adopt this when procurement, audit, or a customer questionnaire forces the question. --- DIAGRAM (page 8, foot): four horizontal bands stacked, each labeled, each with its maturity marker at the right edge. Bands get narrower toward the top to indicate adoption funnel. An arrow at the left marked "start here" points at Layer 1. --- What it is not This section exists because mis-set expectations are the most common cause of abandonment, and every item below has caused a real "wait, I thought it did X" moment. It is not a replacement for git. It wraps git. Your repositories stay normal git repositories. Your teammates who do not use SecureGit are unaffected. You can stop using it at any time and lose nothing but the receipts. It is not a malware sandbox. It prevents acquisition-time execution and it scans. It does not analyze behavior, emulate, or detonate anything. Code you subsequently choose to build and run is code you chose to build and run. It is not a SAST platform. It is not competing with Semgrep or SonarQube on depth of static analysis. It wraps them. If you need deep dataflow analysis, you need those tools, and SecureGit's job is to run them at the right moment and anchor their output. It is not a secrets manager. It brokers access to secrets that live in a real secrets manager. It is not where your secrets should live. (Page 47.) It is not a bundled vulnerability scanner — with one deliberate, narrow exception documented on page 40. It anchors the output of the scanners you already run. That boundary was a decision, it was contested internally, and page 40 explains why it moved once and why it will not move again casually. It does not make your history trustworthy retroactively. Commits made before you adopted it have no receipts. There is a path for retro-attestation, and it is honest about being a different tier of evidence. A receipt that says "we checked afterward" is worth less than one that says "we watched it happen," and the system records which one you have. --- SIDEBAR (page 9, foot, boxed): The three-word test Whenever you are unsure whether SecureGit is involved in something, ask: is this a boundary crossing? Code arriving from elsewhere — yes. Code leaving to shared infrastructure — yes. Anything purely local, in your working tree, between you and your own disk — no. status, log, diff, add, checkout, branch, stash cross no boundary and emit no receipts. That is deliberate. A tool that instruments everything gets turned off. --- PAGE 10 — PART I: SECTION OPENER Full-bleed. Reversed: paper type on ink ground. Type only. PART ONE DAY ONE Ten minutes to your first scan. An evening to a changed workflow. Nothing on these pages requires a decision from anyone but you. (Foot line, mono, orange:) 11 → 23 --- PAGE 11 — THE TEN-MINUTE QUICKSTART Headline: TEN MINUTES Deck: Five commands. No configuration. No account. Nothing to uninstall afterward except one binary. DESIGN NOTE: This page is the single most important page in the issue and should be designed as a self-contained card that survives being screenshotted and shared out of context. Large terminal blocks, generous spacing, numbered steps with hanging mono numerals in signal. Every command on one line, no wrapping. --- 1 · Install curl -fsSL https://