perimetercli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Perimeter Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+<div align="center">
+
+# Perimeter
+
+**Security and cost audit for your AI agent toolchain — MCP servers, hooks and skills.**
+
+```
+perimeter audit
+```
+
+Zero runtime dependencies · Works offline · Open-core (MIT)
+
+[![Node](https://img.shields.io/badge/node-%3E%3D18-43853d?logo=node.js&logoColor=white)](https://nodejs.org)
+[![npm](https://img.shields.io/npm/v/perimetercli)](https://www.npmjs.com/package/perimetercli)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+</div>
+
+---
+
+## The problem
+
+Teams are wiring AI agents to MCP servers, Claude Code hooks, Cursor rules and
+Codex skills faster than they can secure or afford them. By default that means:
+
+- **Tool poisoning** — malicious instructions tucked inside a tool description
+  that the agent blindly obeys.
+- **Dangerous capability** — a server that can run shell, write files, read
+  credentials, or move money.
+- **Context bloat** — several large servers can eat **30k+ tokens** before the
+  agent does anything useful.
+- **Silent drift** — a tool changes since you last looked, and nobody notices.
+
+## What Perimeter does
+
+One command answers three questions at once:
+
+1. **Risk** — what can each server, tool, hook and skill actually *do*?
+2. **Cost** — how much context and money do they burn per load?
+3. **Change** — did a tool quietly change since I last audited?
+
+```bash
+perimeter audit                 # human-readable verdict + findings
+perimeter audit --enforce       # gate CI (exit 1 on a finding)
+perimeter audit --json          # machine-readable
+perimeter baseline              # record a signature hash for drift
+perimeter cost                  # token/cost footprint only
+perimeter session               # observe what agents actually ran
+perimeter guard --server "npx -y @modelcontextprotocol/server-filesystem"
+perimeter serve                  # preview the generated report
+perimeter server                 # self-hosted fleet dashboard (Pro)
+perimeter push <url>             # send an audit to a Perimeter server
+```
+
+## Why it's different
+
+| Risk | Perimeter | Most MCP scanners | Enterprise gateways |
+| --- | --- | --- | --- |
+| MCP servers | ✅ | ✅ | ✅ |
+| Claude Code hooks / settings | ✅ | ❌ | ⚠️ |
+| Cursor / Codex skills + `AGENTS.md` | ✅ | ❌ | ⚠️ |
+| **Token & cost footprint** | ✅ | ❌ | ⚠️ |
+| **Baseline + drift detection** | ✅ | ⚠️ | ⚠️ |
+| **CI gate (`--enforce`)** | ✅ | ⚠️ | ⚠️ |
+| Local · offline · zero-dep | ✅ | some | ❌ |
+
+## Install
+
+```bash
+npm install --global perimetercli
+```
+
+Requires Node 18+. Works on macOS, Linux and Windows.
+
+## Quick start
+
+```bash
+cd my-project
+perimeter audit              # scan from the current directory
+perimeter baseline           # record a baseline for drift detection
+perimeter audit --enforce --fail-on high
+```
+
+Here's what an audit of a risky setup looks like:
+
+```text
+Verdict: CRITICAL
+  1 critical · 2 high · 5 medium · 4 low
+
+[CRITICAL] INJECT-001 · Tool poisoning: likely injection in tool description
+[HIGH]     RISK-SHELL  · Arbitrary command execution
+[HIGH]     RISK-PAYMENT · Payment / financial capability
+[MEDIUM]   RISK-FSWRITE · Filesystem write access
+[MEDIUM]   SUP-CREDS-ENV · Secrets present in server config env
+
+Cost: model claude-sonnet · ~8,652 tokens/load · $0.09/load
+```
+
+## What it detects (OWASP Agentic-aligned)
+
+- **INJECT-001** — tool poisoning / prompt injection in tool metadata
+- **INJECT-002** — suspicious instructions in `AGENTS.md`/`CLAUDE.md`/skills
+- **SECRET-LEAK** — a credential-looking value in an agent context file
+- **HOOK** — risky Claude Code hooks (arbitrary code on tool use / session start)
+- **RISK-SHELL / RISK-EXFIL / RISK-PAYMENT / RISK-CREDS / RISK-CLOUD**
+- **RISK-FSWRITE** — filesystem writes
+- **SUP-TYPOSQUAT** — package names one edit from a well-known server
+- **SUP-UNVERIFIED / SUP-UNPINNED / SUP-CREDS-ENV** — supply-chain concerns
+- **TOK-BLOAT** — a server whose tool schemas eat too much context
+- **DRIFT-NEW / DRIFT-CHANGED** — new or mutated servers vs. your baseline
+
+`perimeter session` goes further: it reads your actual agent session logs and
+reports what was *really* called (Bash `×3`, Write `×1`…), with exact token
+spend when the log records it.
+
+## Runtime guard
+
+`perimeter guard` proxies a real MCP server and **blocks risky tool calls at
+runtime** based on a fail-closed policy. Point your agent at Perimeter instead of
+the server directly:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "perimeter",
+      "args": [
+        "guard",
+        "--server",
+        "npx -y @modelcontextprotocol/server-filesystem",
+        "--allow",
+        "Read,Glob,List"
+      ]
+    }
+  }
+}
+```
+
+Every call is logged to `.perimeter/guard.log.jsonl` for review.
+
+## Hosted dashboard (self-host)
+
+For a team, run a local dashboard and push audits to it — a self-hosted version of
+the Pro continuous-audit loop:
+
+```bash
+perimeter server --port 4173
+perimeter audit --json | perimeter push http://localhost:4173 --project acme
+```
+
+Open `http://localhost:4173` to see verdicts, findings and cost for every project
+you push.
+
+## CI
+
+```yaml
+- run: npm install --global perimetercli
+- run: perimeter baseline
+- run: perimeter audit --enforce --fail-on high --out perimeter-report
+- uses: actions/upload-artifact@v4
+  with: { path: perimeter-report/ }
+```
+
+Perimeter emits **SARIF** too, so findings land directly in GitHub code scanning.
+
+## Configuration
+
+```bash
+perimeter init
+```
+
+Creates `.perimeter/config.json`:
+
+```json
+{
+  "failOn": "critical",
+  "model": "claude-sonnet",
+  "budget": 1,
+  "maxTokensPerServer": 5000,
+  "block": ["@modelcontextprotocol/server-everything"],
+  "allow": [],
+  "ignoredRules": []
+}
+```
+
+## Pro (open-core)
+
+The CLI is free and MIT. Perimeter Pro adds team policy, hosted dashboards,
+remote-server analysis and drift alerts — see [`PRICING.md`](PRICING.md) and
+[`docs/pro.md`](docs/pro.md).
+
+## Contributing
+
+Read [`CONTRIBUTING.md`](CONTRIBUTING.md), then:
+
+```bash
+npm install
+npm test
+```
+
+## License
+
+[MIT](LICENSE)

package/bin/perimeter.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli.js";
+
+main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "perimetercli",
+  "version": "0.1.0",
+  "description": "Security and cost audit for your AI agent toolchain — MCP servers, hooks, skills. One command finds poisoning, dangerous capabilities, context bloat and drift, and gates CI.",
+  "type": "module",
+  "bin": {
+    "perimeter": "./bin/perimeter.js"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./cli": "./src/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "start": "node bin/perimeter.js"
+  },
+  "keywords": [
+    "security",
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "supply-chain",
+    "agent-security",
+    "tool-poisoning",
+    "prompt-injection",
+    "sbom",
+    "cost",
+    "tokens",
+    "devsecops",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Perimeter Contributors",
+    "email": "hello@perimetercli.dev"
+  },
+  "homepage": "https://perimetercli.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/perimetercli/perimeter.git"
+  },
+  "bugs": {
+    "url": "https://github.com/perimetercli/perimeter/issues"
+  }
+}

package/src/audit.js

@@ -0,0 +1,164 @@
+import path from "node:path";
+import fs from "node:fs";
+import { discover } from "./discover.js";
+import { runRules, runContextRules, overallVerdict, verdictOf } from "./rules.js";
+import { estimateCost, tokensForTools, resolveModel } from "./tokens.js";
+import { readJson, writeJson, sha256, isoNow } from "./util.js";
+
+export const DEFAULT_POLICY = {
+  failOn: "critical",
+  model: "claude-sonnet",
+  budget: null,
+  maxTokensPerServer: 5000,
+  allow: [],
+  block: [],
+  ignoredRules: [],
+};
+
+function normalizeConfig(filePath, cliOpts) {
+  const onDisk = readJson(filePath) || {};
+  const merged = { ...DEFAULT_POLICY, ...onDisk, ...cliOpts };
+  return merged;
+}
+
+export function baselinePath(cwd) {
+  return path.join(cwd, ".perimeter", "baseline.json");
+}
+
+export function policyPath(cwd) {
+  return path.join(cwd, ".perimeter", "config.json");
+}
+
+export function makeBaseline(cwd, servers) {
+  const map = {};
+  for (const s of servers) {
+    map[s.id] = {
+      displayName: s.displayName,
+      source: s.source,
+      signature: s.signature,
+      packageName: s.packageName,
+    };
+  }
+  return {
+    version: 1,
+    created: isoNow(),
+    servers: map,
+  };
+}
+
+export function writeBaseline(cwd, servers) {
+  const baseline = makeBaseline(cwd, servers);
+  writeJson(baselinePath(cwd), baseline);
+  return baseline;
+}
+
+function loadBaseline(cwd) {
+  return readJson(baselinePath(cwd));
+}
+
+/**
+ * Run a full audit.
+ * opts: { cwd, configPath, model, budget, failOn, useBaseline, home, recursive }
+ */
+export async function runAudit(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const config = normalizeConfig(
+    opts.configPath || policyPath(cwd),
+    {
+      model: opts.model,
+      budget: opts.budget ?? undefined,
+      failOn: opts.failOn,
+      maxTokensPerServer: opts.maxTokensPerServer,
+    }
+  );
+  const { servers, hooks, contextFiles, errors, files } = discover(cwd, {
+    home: opts.home,
+    recursive: opts.recursive,
+  });
+
+  const baseline = opts.useBaseline !== false ? loadBaseline(cwd) : null;
+  const allServers = [...servers, ...hooks];
+  const serverResults = allServers.map((server) => {
+    const result = runRules(server, {
+      config,
+      baseline,
+      cost: config.model,
+    });
+    server.verdict = result.verdict;
+    return { server, ...result };
+  });
+
+  // Instruction / skill files — the context an agent reads every session.
+  const contextFindings = contextFiles
+    .filter((c) => c.content)
+    .flatMap((c) => runContextRules(c));
+
+  // Cost summary across all servers.
+  let totalTokens = 0;
+  for (const { server } of serverResults) {
+    totalTokens += server.estimatedTokens || 0;
+  }
+  const cost = estimateCost(totalTokens, config.model);
+  const budget = config.budget ? Number(config.budget) : null;
+  const costs = {
+    model: cost.model,
+    inputRate: cost.inputRate,
+    outputRate: cost.outputRate,
+    estimated: cost.estimated,
+    totalTokens,
+    perLoadCost: cost.perLoad,
+    budget,
+    loadsPerDayWithinBudget:
+      budget && cost.perLoad > 0 ? Math.floor(budget / cost.perLoad) : null,
+    overBudget: budget != null && cost.perLoad > budget,
+  };
+
+  const verdict = overallVerdict(serverResults);
+  const findings = [...serverResults.flatMap((r) => r.findings), ...contextFindings];
+  const blocked = findings.filter((f) =>
+    config.block.some((b) => b && (f.packageName || "").toLowerCase().includes(b.toLowerCase()))
+  );
+
+  // Apply allow/block/ignore filtering for the effective verdict.
+  const effectiveFindings = findings.filter(
+    (f) => !config.ignoredRules.includes(f.id) && !blocked.includes(f)
+  );
+  const effectiveVerdict = verdictOf(effectiveFindings);
+
+  const model = resolveModel(config.model);
+
+  return {
+    generatedAt: isoNow(),
+    cwd,
+    config: {
+      failOn: config.failOn,
+      model: config.model,
+      budget: config.budget,
+      maxTokensPerServer: config.maxTokensPerServer,
+    },
+    servers: serverResults.map((r) => ({
+      id: r.server.id,
+      displayName: r.server.displayName,
+      source: r.server.source,
+      transport: r.server.transport,
+      packageName: r.server.packageName,
+      command: r.server.command,
+      url: r.server.url,
+      capabilities: r.capabilities,
+      verdict: r.verdict,
+      estimatedTokens: r.server.estimatedTokens,
+      catalogName: r.server.catalog?.name || null,
+      findings: r.findings,
+    })),
+    findings,
+    contextFindings,
+    effectiveFindings,
+    verdict,
+    effectiveVerdict,
+    counts: verdict.counts,
+    costs,
+    contextFiles: contextFiles.map((c) => ({ file: c.file, kind: c.kind, label: c.label })),
+    errors,
+    files,
+  };
+}