GhostGrant

---

[!WARNING] GitHub and Slack are wired up so far. check --live asks GitHub and Slack; AWS, Okta and Google Workspace answer unknown until their adapters land. See the roadmap.

💡 What it's for

When a team shuts down an AI agent, somebody clicks revoke on its tokens and keys and moves on. Nobody goes back to see whether the GitHub token still answers, whether the AWS key got cached into some other job, or whether the Slack bot quietly came back after a reinstall. GhostGrant does the going back.

You write a YAML manifest naming the credentials the agent held: type and identifier, never the secret itself. GhostGrant asks each provider's own introspection endpoint whether each one is dead, records the answer, and asks again at 24h, 7d, 30d and 90d. If a credential flips from dead to alive between checks, it raises an alert. At the end you get a dated report saying what was checked and what happened.

It is a local CLI. There's no GhostGrant server, no account, and no telemetry.

📊 Features

Feature	Status
ghostgrant decommission <manifest>	✅ Records a decommission entry with a timestamp and the manifest's checksum. Manifest format
ghostgrant check --mock	✅ Runs every check that's due against canned responses and prints alive/dead
ghostgrant check --live	✅ GitHub: asks GET /user with each token you pipe in. 200 is alive, 401 is dead, a timeout, 5xx or rate limit is unknown. Live checks
Slack adapter	✅ check --live asks Slack's auth.test. ok: true is alive; invalid_auth, token_revoked or account_inactive is dead; any other error, a 429, 5xx or timeout is unknown.
Re-check windows and flip alerts	✅ Each check runs the window that's due (at decommission, then 24h, 7d, 30d, 90d) and skips records with nothing due. Dead-to-alive prints an ALERT and goes to alerts.log.
ghostgrant report <agent>	✅ A dated plain-text report of every check for one agent and what it found, or the same data with --json. Reports
Agent Security Suite inventories	✅ ghostgrant import <inventory.json> records every retired identity in the suite's shared format; ghostgrant export --format inventory writes the checks back as lastVerifiedDeadAt and critical findings. Both validate against the vendored schema. Inventory format
AWS IAM, Okta, Google Workspace	Slices 5 to 7
Static demo dashboard	✅ site/ renders a bundled report for a fictional agent (GitHub credentials, every window, one flip) with the CLI's own Report type. npm run build writes it to _site/site/, and the Pages workflow publishes it to ghost-grant-demo.ai-automation-tools.dev on every push to main. The page links the same sample as a downloadable inventory

🚫 What it won't do

These are out of scope on purpose, so please don't open an issue asking for them. The spec says why.

• Revoke or rotate anything. GhostGrant only asks read-only introspection endpoints. It never holds a credential that can change anything at a provider.
• Sign or "attest" its reports. A report says what was checked and what each provider answered. It isn't audit-grade or compliance evidence.
• Run as a hosted service. No server, no dashboard, no account, no billing. The demo page is static.
• Support providers beyond the five. GitHub, Slack, AWS IAM, Okta and Google Workspace, and nothing else this version.

🚀 Quick start

# 1. Install dependencies (Node 22.18 or newer)
npm install

# 2. Build the CLI into dist/ and the demo page into _site/site/
npm run build

# 3. Record the example manifest (format: docs/manifest.md) and check it in mock mode
node dist/cli.js decommission examples/manifest.yaml
node dist/cli.js check --mock
node dist/cli.js report billing-bot --mock

# 4. Tests and lint
npm test && npm run lint

node dist/cli.js --help lists every command and flag, and --version prints the version. Records live under $GHOSTGRANT_HOME (default ~/.ghostgrant); point it somewhere else to try things without touching your real records.

🔑 Live checks

check --live needs the tokens themselves, which the manifest never holds. Pipe them in on stdin, one per line. Each token goes to the credential whose prefix it starts with, is sent to that provider once, and is dropped when the run ends. Nothing prints or stores it.

printenv OLD_AGENT_GH_TOKEN OLD_AGENT_SLACK_TOKEN | node dist/cli.js check --live

A credential with no matching token, or more than one, reports unknown and nobody is called. So does every provider that doesn't have an adapter yet. unknown never counts as dead.

⏱️ Re-checks and alerts

Each credential gets checked at decommission, then 24 hours, 7 days, 30 days and 90 days after it. Run ghostgrant check as often as you like, by hand or from cron: it only asks about the window that's due and says when the next one is. If you miss a window, the next run checks the latest one that's due instead. An unknown answer doesn't settle a window, so the next run asks again.

A credential whose last definite answer was dead and now answers alive prints an ALERT line and adds one JSON line to $GHOSTGRANT_HOME/alerts.log. Mock and live answers are kept apart, so a canned answer never counts as a real check.

📄 Reports

ghostgrant report <agent> prints every live check for one agent: each credential, each window, when it was asked and what came back, with any dead-to-alive flip marked. Add --mock to report the mock checks instead (the two are never mixed), and --json for the same data as JSON. The JSON shape is the Report type in src/report.ts.

The last line says what the checks add up to:

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗