Documentation

1Introduction

1.1What is eyebrow?#

eyebrow is the integrity layer for everything AI coding agents install and run — skills, MCP servers, plugins, hooks and rules.

It discovers every artifact installed across your AI tools, fingerprints them into a committable lockfile, catches the moment an approved artifact silently changes, and can sandbox what runs at runtime. It ships as a single self-contained binary, runs entirely on your machine, and never uploads your code or secrets.

The product in one line: know what's installed, prove it hasn't changed, see what ran, and catch the sleeper before it fires.

1.2The problem#

AI coding agents became useful the moment they could extend themselves — pulling a skill from a gist, an MCP server from a registry, a plugin from a tap, a hook from a dotfiles repo. That extensibility is most of the magic. It is also, structurally, a package manager nobody audits.

Each of those artifacts is third-party code, fetched once and then executed with your full environment: your credentials, your cloud access, your source code. Unlike npm or pip, there is no lockfile, no review gate, no pinned version, no diff your teammates can see.

Four questions no team can answer today:

• You don't know what's installed. Artifacts hide in a dozen tool-specific locations. No single inventory exists.
• You can't prove it's still what you reviewed. Artifacts can rewrite themselves in place, with no version bump.
• You can't see what actually ran. "This skill can read your credentials" is a hypothesis; "it read them 40× this week" is an incident.
• The sleeper case is invisible. Installed long ago, never used, silently changed, then fires for the first time — no static scanner sees it.

1.3Core principles#

1.4Who eyebrow is for#

2Quick start

From nothing to a verified baseline in about two minutes.

2.1Install#

Homebrew (macOS / Linux):

brew install alexverify/tap/eyebrow

Go:

go install github.com/alexverify/eyebrow/cmd/eyebrow@latest

Install script:

curl -fsSL https://eyebrow.cc/install.sh | sh

Or download a signed release binary from GitHub and verify its checksum. eyebrow is a single static binary with no runtime dependencies.

2.2Your first scan#

Run eyebrow scan in any directory. It is read-only and touches nothing:

$ eyebrow scan

  scanning AI coding tools…
  ~/.claude/skills/           12 skills
  ~/.claude/plugins/           3 plugins
  .claude/settings.json        hooks + mcp
  .mcp.json                    4 MCP servers

  → 19 artifacts fingerprinted   3 findings (1 high)

2.3Freeze the baseline#

Write the lockfile and commit it alongside your code:

$ eyebrow lock
  wrote eyebrowlock.json  (19 artifacts)

$ git add eyebrowlock.json && git commit -m "pin agent artifacts"

2.4Verify later#

Any time after — or in CI — check the disk against the approved baseline:

$ eyebrow verify
  OK  18 artifacts unchanged
  !!   1 drifted: mcp:aws-helper
       + tools/postinstall.sh  (added)

3Core concepts

3.1Artifacts#

An artifact is any unit of third-party code or instruction your AI tool loads. eyebrow treats them all the same way: discover, fingerprint, analyse, watch.

3.2Fingerprints and the lockfile#

A fingerprint is a canonical, cross-platform content hash of an artifact — stable across operating systems and line endings, and deliberately excluding volatile data (timestamps, caches) so integrity checks never produce false positives.

The lockfile (eyebrowlock.json) records every artifact's identity, version, fingerprint, capabilities and provenance. It is designed to be committed to your repository and reviewed like any other dependency change.

Crucially, the lockfile is content-free: it contains hashes and verdicts, never your source.

3.3Drift#

Drift is any difference between what is on disk now and what the lockfile approved. eyebrow classifies drift as expected (you updated something deliberately) or unexpected, and names exactly which files were added, removed or modified — without ever storing your code.

Drift is the core insight of the product: the danger is rarely what you installed. It is what that thing became afterwards.

3.4The sleeper attack#

The textbook supply-chain attack, and the one no pure-static scanner can see:

• An artifact is installed and reviewed. It looks fine, because it is fine.
• It sits dormant for weeks. Never invoked.
• A maintainer account is compromised, or a "no version bump" update lands. The content mutates on disk.
• It runs for the first time — and reads your cloud credentials.

No single signal catches this. You need three, fused:

• capability — what the artifact is able to reach (secrets, network, shell)
• drift — whether its content changed since you approved it
• usage — whether this is the first time it has ever executed

capability × drift × usage = sleeper

Most tools own one of these signals. eyebrow owns all three, locally, which is why it can produce a verdict a single-layer or cloud-static scanner structurally cannot.

3.5Capability analysis#

Static analysers flag what an artifact is able to do, with the pattern and context that triggered the finding. Typical detections:

• Credential and secret access — reading ~/.ssh, ~/.aws, .env files
• Network egress — outbound calls, especially paired with local file reads
• Shell-out and obfuscation — curl … | sh pipes, eval/atob indirection
• Install-time execution — npm install hooks, postinstall scripts
• Consent-bypass language buried in rule or instruction files

Findings are advisory, not absolute. You can approve, ignore or mark an artifact as safe — decisions are recorded in the lockfile so they are reviewable.

3.6Content-free and local-first#

Two guarantees that define the architecture:

• Local-first — the core job needs no network. Optional network features fall back to local silently when unreachable.
• Content-free — anything that ever leaves a machine carries identifiers, fingerprints and verdicts only. Never source code. Never secrets. Enforced at the boundary, not promised in a blog post.

4Products

4.1Overview#

4.2Local audit — the snapshot#

The read-only wedge, and the foundation of everything else. Run it anywhere, commit the result, review it like any other dependency change.

• Cross-tool discovery across 11 AI coding tools on macOS, Linux and Windows.
• Tamper-evident fingerprinting into a committable lockfile.
• Behavioural scanning with findings, patterns and context.
• Drift detection naming exactly which files changed.
• Cryptographic signing and a provenance ladder tracing each artifact to its origin.
• A stable pass/fail contract so CI can gate on it.

4.3Continuous monitoring#

The upgrade from a manual check to always-on watching. Scheduled re-verification, real-time alerts the moment something drifts, dormancy tracking, and first-execution signals that make the sleeper detector possible.

Security you run once is a snapshot. Watching over time is where the drift and sleeper risk actually lives. See §10 Access & pricing for how continuous access works.

4.4Runtime MCP firewall#

Fingerprinting tells you what an artifact could do. The firewall controls what it actually does while running.

4.5Local dashboard#

Run eyebrow dashboard for a private, on-your-machine view of every artifact: trust verdict, provenance, capability diff, file manifest, runtime activity, and last-used/dormancy — with one-click approve, quarantine, freeze, mute and egress-allow actions.

4.6Quality & cost report#

The same scan that finds security problems already reads and measures every add-on. That data answers a second question most teams have never measured: what is your AI setup costing you before it does any work?

"Your assistant loads 23 add-ons. Eleven have never fired. They consume nearly a fifth of its working memory before you type a word. Here are the three worth rewriting, and here's the rewrite."

Security tools get opened after an incident. Cost tools get opened every week.

4.7eyebrow for Teams#

Everything above protects one machine. Teams is the shared view across all of them.

5Architecture

5.1System overview#

   AI coding tools                eyebrow                     outputs
  ┌────────────────┐        ┌──────────────────┐        ┌──────────────────┐
  │ Claude Code    │        │  Discovery       │        │ eyebrowlock.json │
  │ Cursor         │───────▶│  Fingerprinting  │───────▶│ findings report  │
  │ Codex          │        │  Analyzers       │        │ CI exit code     │
  │ Gemini CLI     │        │  Verify / drift  │        │ local dashboard  │
  │ Windsurf       │        ├──────────────────┤        ├──────────────────┤
  │ Copilot CLI    │        │  Runtime shim    │        │ audit log        │
  │ OpenCode  …    │◀──────▶│  (wrap / policy) │───────▶│ (digests only)   │
  └────────────────┘        └──────────────────┘        └──────────────────┘
                                     │
                                     ▼   (opt-in, content-free)
                            .eyebrow/fleet  →  git  →  team blast-radius

5.2Discovery engine#

eyebrow knows where each tool hides its artifacts, on every supported OS, and builds one inventory from all of them.

5.3Fingerprinting#

Canonical hashing normalises line endings and path separators so the same artifact fingerprints identically on macOS, Linux and Windows. Volatile content — timestamps, caches, logs — is deliberately excluded so an integrity check never fires a false positive on noise.

5.4Analyzers#

Analyzers are pattern-and-context detectors that produce findings with a severity. They are designed to be extensible: the roadmap includes an analyzer plugin SDK so detection breadth becomes a community asset rather than a hiring problem.

5.5Runtime shim#

The shim sits between your agent and an MCP server, speaking the protocol transparently in both directions. It enforces per-tool policy, proxies egress with secret redaction, launches the server inside an OS sandbox, and writes a tamper-resistant audit log of digests.

5.6Fleet: git as the backend#

Each machine exports a content-free snapshot to .eyebrow/fleet in a repository your team already has: ids, fingerprints and verdicts — no source, no secrets. eyebrow fleet reads those commits to answer blast-radius questions.

No server is required for small teams. The result is fleet visibility without telemetry upload — the anti-MDM model.

5.7Signing and trusted keys#

Sign the lockfile with a local ed25519 key and register your teammates' public keys in eyebrow.trustedkeys. Approvals then trace to a person, not a vibe, and CI can enforce: only approved, unmodified, clean, signed-by-us artifacts run here.

5.8The privacy boundary#

6CLI reference

6.1Exit codes#

7Onboarding guides

7.1Solo developer#

• Install eyebrow and run a scan to see your full surface for the first time.
• Review the findings. Approve what you recognise; investigate what you don't.
• Write the lockfile and commit it.
• Re-run verify whenever you update tools, or enable continuous monitoring so it watches for you.
• Wrap any MCP server that touches real credentials.

7.2Team setup#

• Standardise on a committed lockfile in each repository.
• Each engineer signs with their own ed25519 key; register public keys in eyebrow.trustedkeys.
• Enable content-free fleet snapshots into a shared repository (.eyebrow/fleet).
• Add the CI gate so a merge fails the moment an artifact drifts or breaks policy.
• Agree a policy: which capabilities require review, and who can approve.

7.3CI integration#

# .github/workflows/eyebrow.yml
name: eyebrow
on: [push, pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install eyebrow
        run: curl -fsSL https://eyebrow.cc/install.sh | sh
      - name: Verify agent artifacts
        run: eyebrow verify --ci

The job fails on drift or policy violation, so "we'll review the agent config later" becomes "the pipeline already did."

7.4Publisher onboarding (badge)#

• Claim your artifact and prove control (repo ownership, DNS TXT, registry, or DID signature).
• Run verification locally or in CI; eyebrow independently fetches and verifies the published artifact.
• Embed the badge snippet in your README and on your site.
• For continuous tiers, connect a release webhook and post the bond.

Target: under 10 minutes from claim to embedded badge. See §9 The badge programme.

8Use cases

8.1Individual developers#

• Adopting an unfamiliar repository — see the whole surface before letting an agent loose on it.
• Catching a rug pull — an approved skill rewrites itself and you get a diff instead of silence.
• Catching a sleeper — dormant, drifted, then it fires for the first time.
• Running agents against real credentials — wrap the MCP servers so denied calls fail cleanly and secrets are redacted.
• Reviewing artifact updates like dependency bumps, in a pull request.
• Trimming waste — find the unused and expensive add-ons dragging on context and cost.

8.2Teams and engineering organisations#

• Fleet inventory across every engineer's machine.
• Blast radius on CVE day — "this artifact drifted; 3 of 8 engineers have it."
• One central policy: approved, signed artifacts only.
• CI gating so drift can't merge.
• Posture history — signed, timestamped evidence of what changed and when.
• Shadow-AI discovery — surface the tools nobody officially sanctioned.

8.3Security, compliance and regulated industries#

• Audit evidence: signed baselines and change history for SOC 2 / ISO-style reviews.
• Data sovereignty and air-gapped operation — everything runs locally, content-free.
• Tamper detection on developer endpoints.

This maps cleanly onto Lean Six Sigma DMAIC, which many compliance and improvement organisations already run:

8.4Agents that hold keys or move money#

• Pre-signature integrity — when an agent holds wallet or signing keys, a drifted MCP server can move funds, not just leak a variable.
• Closing the after-the-fact gap — an on-chain ledger proves what happened; eyebrow prevents the wrong thing from running.
• Copy-trading and strategy networks — verify the strategy you're copying runs unmodified, approved components.

8.5Publishers, marketplaces and platforms#

• A live verification mark for listings, checkable by humans and machines.
• Verified publisher identity — turn an anonymous author into an accountable one.
• Catalog-wide verification for a registry or marketplace.

8.6Infrastructure and node operators#

• Client and node-software integrity, so a compromised update cannot quietly turn honest hardware malicious.
• Signed baselines for operators running software behind staked wallets.

9The eyebrow badge

9.1What the badge claims#

The badge is a live, checkable claim that a published artifact is exactly what its publisher says it is, and hasn't changed since it was verified.

"This is the code they published. It hasn't changed. Here's what it can reach."

It is not a safety guarantee, a full code audit, or a promise the artifact is bug-free. eyebrow verifies identity and integrity, and reports capability findings. It does not certify intent. This precision is deliberate: it is the only claim that is provable, continuously checkable, and falsifiable.

9.2Tiers#

Free one-time badges buy ubiquity; continuous badges carry meaning. A badge that was true once is the exact failure mode eyebrow exists to catch.

9.3Badge states#

9.4Technical contract#

https://badge.eyebrow.cc/<publisher>/<artifact>.svg    → live badge image
https://badge.eyebrow.cc/<publisher>/<artifact>.json   → machine-readable state
https://eyebrow.cc/verify/<publisher>/<artifact>       → human verification page

Embed in a README:

[![Verified by eyebrow](https://badge.eyebrow.cc/acme/mcp-server.svg)]
(https://eyebrow.cc/verify/acme/mcp-server)

The JSON response carries state, tier, version, content hash, verification timestamps, capabilities, findings counts, bond status, publisher identity, and a signature — so badge state can be verified without trusting eyebrow's server.

9.5Conditions and rules#

Eligibility#

• The artifact must be publicly retrievable at a stable identifier.
• The publisher must prove control of it.
• It must pass the scan with zero critical findings.
• The publisher accepts the terms, including that eyebrow may withdraw a badge at any time.

Automatic state changes#

Grace and appeal#

• Drift opens a 72-hour grace window; the badge shows amber publicly during it — no silent hiding.
• A failed state for a critical finding is immediate, with no grace period.
• Appeals follow a published, time-bound review process, and decisions are public.

9.6Bonds#

A bond is a refundable security deposit. To carry a continuous badge, a publisher locks $BROW as collateral behind their claim. They keep ownership; it is returned in full on graceful exit. It is slashed only through a published adjudication process if the artifact is proven to have shipped malicious code under a green badge.

• Skin in the game — the publisher's incentive aligns with the user's.
• Sybil resistance — you cannot cheaply create many fake verified publishers.
• Insurance — a real pool exists to compensate affected users.

Bond size scales to blast radius: a formatting skill and a wallet-signing MCP server are not the same risk.

9.7Why this badge is different#

• It's live, not a snapshot — it changes state when reality changes.
• It's falsifiable — anyone can check the endpoint or verify the signature.
• The publisher can't fake it — eyebrow controls the image and timestamps.
• It's economically backed by a bond.
• It publishes failures, including past drift events. Showing amber is what makes green mean something.
• It's machine-readable, so agents can check before installing.
• The auditor is auditable — open source, content-free, signed attestations.

10Access & pricing

10.1The access ladder#

The line, stated plainly: a one-time check of your own machine is always free. Watching it continuously over time is the paid upgrade.

10.2Why the split falls here#

eyebrow's engine is open source under MIT. A token gate on a purely local binary would be neither meaningful nor enforceable — anyone could fork it. So the free floor is genuinely free, and the paid tiers sit where value actually requires eyebrow's hosted service: continuous alerting, reputation lookups, cross-machine state and coordination.

Nobody ever pays to be safe. You pay for coordination, scale, and supply-side trust.

10.3Commitment#

We publish what stays free forever before the paid product exists, and we do not move something already free behind a paywall. A company selling protection against bait-and-switch cannot look like one.

11$BROW

11.1The one rule#

The local layer never requires a token. Scanning, locking, verifying and wrapping work with no wallet, no network and no $BROW. The token lives exclusively in the optional network and coordination layer.

11.2Utility#

11.3What $BROW is not used for#

• Gating the local CLI or the free snapshot.
• Pay-per-scan of your own machine.
• Emissions or staking yield.
• Direct revenue share to holders.

12The ecosystem loop

Every part of eyebrow feeds the next. Two things compound with every install: the fingerprint dataset, and $BROW demand.

(A) FREE SNAPSHOT      → devs install, see their surface, first fingerprints
(B) CONTINUOUS         → hold $BROW · recurring use · richer fingerprints
(C) FINGERPRINT DATA   → the only record of what "normal" looks like
(D) THE BADGE          → publishers bond $BROW · verified mark on their sites
        └→ backlinks + end-user reach → new devs → back to (A)
(E) TEAMS (paid)       → revenue → buyback-and-burn → $BROW value → back to (B)
(F) AGENT ORACLE       → agents pay per lookup · scales with #agents, not #humans

13Roadmap

13.1Deeper capabilities on the roadmap#

• Universal activation telemetry — last-used and dormancy for every artifact kind, not just wrapped MCP servers.
• The sleeper detector — install-age × content-drift × first-ever invocation, fused into one alert.
• Line-level rug-pull proof — a red/green diff showing the exact line that was slipped in.
• Exercised-risk ranking — re-rank findings by what actually ran; mark capabilities reachable or unreachable.
• Network-effect reputation — "trusted by N other users, first seen <date>" — hash-only, opt-in, silent offline.

14Security & privacy

14.1What eyebrow collects#

By default, nothing leaves your machine. There is no account, no telemetry, and no upload in the core product. Optional network features are explicitly opt-in and carry fingerprints and verdicts only.

14.2Threat model — what eyebrow covers#

• Artifact tampering after approval (rug pulls, silent republishing).
• Sleeper artifacts: dormant, drifted, then first execution.
• Undeclared capabilities: secret access, network egress, shell-out, install hooks.
• Runtime misbehaviour of MCP servers — contained via policy, redaction and sandboxing.
• Unreviewed contributions — enforced via signed lockfiles, trusted keys and the CI gate.

14.3What eyebrow does not cover#

• Prompt injection and model-level manipulation at inference time.
• The reasoning of the agent harness itself.
• Vulnerabilities in code that has not changed since you approved it.
• Anything outside the artifact supply chain — network, OS and identity security remain your responsibility.

Naming the boundary is deliberate. A security tool that claims to cover everything can't be trusted on anything.

14.4Auditing eyebrow itself#

• Open source under MIT — read every line.
• A single static Go binary; dependency surface kept close to zero (standard library plus a TOML parser for Codex configs).
• Releases ship checksums and build provenance so you can prove the binary came from the repository's release workflow.
• Or build from source; it needs only Go.

14.5Reporting a vulnerability#

Report security issues privately through the repository's security advisory process rather than a public issue. Coordinated disclosure is welcome and credited.

15Integrations & ecosystem

eyebrow is designed to sit underneath other agent infrastructure rather than compete with it. Typical integration shapes:

Integration enquiries and partnership proposals are welcome through the contacts in §17.

16FAQ

Does eyebrow upload my code?#

No. The core product runs entirely locally. Optional network features carry fingerprints and verdicts only — never source, never secrets.

Do I need an account to use it?#

No. Install the binary and run a scan. No account, no wallet, no signup for the local snapshot.

Is it open source?#

Yes, MIT licensed. The engine is auditable, which is the only honest way to ship a tool with this much access.

What's the difference between a snapshot and continuous monitoring?#

A snapshot is a check you run; continuous monitoring watches for you and alerts the moment something drifts. Snapshots are free; continuous is the paid or token-held upgrade.

Why is a token involved at all?#

Only in the network layer — continuous access, publisher bonds, staked attestation. It provides sybil resistance and collateral, which a subscription alone cannot. The local layer never needs it.

Will this slow down my agents?#

No measurable impact for scanning, which is read-only and on-demand. The runtime firewall adds a thin protocol shim and is opt-in per server.

What if eyebrow's servers are down?#

Everything local keeps working. Network features degrade to local silently by design.

Does it work on Windows?#

Yes for discovery, fingerprinting and verification. OS sandboxing is not available on Windows, and eyebrow tells you so rather than pretending otherwise.

How is this different from a normal SCA scanner?#

Scanners check dependencies at a point in time, usually in the cloud. eyebrow fuses capability, drift and runtime usage locally — which is the only way to catch a sleeper.

Can I use it in an air-gapped environment?#

Yes. That is a first-class use case; there is no required network call.

What happens if a badge holder rug-pulls?#

The badge flips state publicly, and for bonded tiers the bond is slashable through a published adjudication process, with proceeds distributed to affected users.

Can I self-host the team features?#

The git-as-backend fleet model is entirely self-managed — your repository, your data. The hosted control plane is an optional convenience.

17Glossary

18Support & community

Contributions are welcome — particularly discovery support as tool layouts change, new analyzers, and incident teardowns for the public library.

eyebrow — know what's installed, prove it hasn't changed, see what ran.