Skip to content
Back to search

https://github.com/n1byn1kt/apitap

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/n1byn1kt--apitap/badge.svg)](/listings/n1byn1kt--apitap)

HTML

<a href="/listings/n1byn1kt--apitap"><img src="/api/listings/n1byn1kt--apitap/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install -g @apitap/core

**Claude Code** — one command to wire it up:

claude mcp add -s user apitap -- apitap mcp

That's it. 12 MCP tools, ready to go. Requires Node.js 20+.

> **Note:** `npx @apitap/core mcp` does not work due to [npm scoped package bin resolution](https://github.com/n1byn1kt/apitap/issues/46). Use `npx apitap mcp` or `apitap-mcp` instead.

> **Optional:** To use `capture` and `browse` (which open a real browser), also run: > ```bash > npx playwright install chromium > ``` > The `read`, `peek`, `discover`, and `import` tools work without it.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 273 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # ApiTap — The MCP Server That Turns Any Website Into an API
  2. > No docs, no SDK, no browser. Just data.
  3. ## What It Does
  4. ApiTap gives AI agents cheap access to web data through three layers:
  5. 1. **Read** — Decode any URL into structured text without a browser (side-channel APIs, og: tags, HTML extraction). 0-10K tokens vs 50-200K for browser automation.
  6. 2. **Replay** — Call captured API endpoints directly. 1-5K tokens per call.
  7. 3. **Capture** — Record API traffic from a headless browser session, generating reusable skill files.
  8. ## MCP Tools (12)
  9. ### Tier 0: Triage (free)
  10. #### `apitap_peek`
  11. Zero-cost URL triage. HTTP HEAD only — checks accessibility, bot protection, framework detection.
  12. ```
  13. apitap_peek(url: string) → PeekResult
  14. ```
  15. **Use when:** You want to know if a site is accessible before spending tokens. Check bot protection, detect frameworks.
  16. **Returns:** `{ status, accessible, server, framework, botProtection, signals[], recommendation }`
  17. `recommendation` is one of: `read` | `capture` | `auth_required` | `blocked` | `not_found` | `error`
  18. **Example:**
  19. ```
  20. apitap_peek("https://www.zillow.com") → { status: 200, recommendation: "read" }
  21. apitap_peek("https://www.doordash.com") → { status: 403, botProtection: "cloudflare", recommendation: "blocked" }
  22. ```
  23. ### Tier 1: Read (0-10K tokens, no browser)
  24. #### `apitap_read`
  25. Extract content from any URL without a browser. Uses side-channel APIs for known sites and HTML extraction for everything else.
  26. ```
  27. apitap_read(url: string, maxBytes?: number) → ReadResult
  28. ```
  29. **Use when:** You need page content, article text, post data, or listing info. Always try this before capture.
  30. **Returns:** `{ title, author, description, content (markdown), links[], images[], metadata: { source, type, publishedAt }, cost: { tokens } }`
  31. If the result has `needsBrowser: true` (with a `hint`), `content` is **not** the page: it renders client-side, redirects via script, or is a bot challenge. Use `apitap_capture`. A failed read carries `cause` (`http_status` | `ssrf` | `transport`) plus `status` and `botProtection` when known.
  32. **Site-specific decoders (free, structured):**
  33. | Site | Side Channel | What You Get |
  34. |------|-------------|-------------|
  35. | Reddit | `.json` suffix | Posts, scores, comments, authors — full structured data |
  36. | YouTube | oembed API | Title, author, channel, thumbnail |
  37. | Wikipedia | REST API | Article summary, structured, with edit dates |
  38. | Hacker News | Firebase API | Stories, scores, comments, real-time |
  39. | Grokipedia | xAI public API | Full articles with citations, search, 6M+ articles |
  40. | Twitter/X | fxtwitter API | Full tweets, articles, engagement, quotes, media |
  41. | Everything else | og: tags + HTML extraction | Title, content as markdown, links, images |
  42. **Examples:**
  43. ```
  44. # Reddit — full subreddit listing, ~500 tokens
  45. apitap_read("https://www.reddit.com/r/technology")
  46. # Reddit post with comments
  47. apitap_read("https://www.reddit.com/r/wallstreetbets/comments/abc123/some-post")
  48. # YouTube — 36 tokens
  49. apitap_read("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
  50. # Wikipedia — 116 tokens
  51. apitap_read("https://en.wikipedia.org/wiki/Artificial_intelligence")
  52. # Grokipedia — full article with citations, 6M+ articles
  53. apitap_read("https://grokipedia.com/wiki/SpaceX")
  54. # Grokipedia — search across 6M articles
  55. apitap_read("https://grokipedia.com/search?q=artificial+intelligence")
  56. # Grokipedia — site stats and recent activity
  57. apitap_read("https://grokipedia.com/")
  58. # Twitter/X — full tweet with engagement, articles, quotes
  59. apitap_read("https://x.com/elonmusk/status/123456789")
  60. # Twitter/X article (long-form post) — full text extracted
  61. apitap_read("https://twitter.com/writer/status/987654321")
  62. # Any article/blog/news — generic extraction
  63. apitap_read("https://example.com/blog/some-article")
  64. # Zillow listing (bypasses PerimeterX via og: tags)
  65. apitap_read("https://www.zillow.com/homedetails/123-Main-St/12345_zpid/")
  66. ```
  67. ### Tier 2: Replay (1-5K tokens, needs skill file)
  68. #### `apitap_search`
  69. Find available skill files by domain or keyword.
  70. ```
  71. apitap_search(query: string) → { found, results[] }
  72. ```
  73. **Use when:** Looking for captured API endpoints. Search by domain name or topic.
  74. #### `apitap_replay`
  75. Call a captured API endpoint directly — no browser needed.
  76. ```
  77. apitap_replay(domain: string, endpointId: string, endpointParams?: object, maxBytes?: number) → ReplayResult
  78. ```
  79. **Use when:** A skill file exists for this domain. This is the cheapest way to get structured API data.
  80. **Returns:** `{ status, data (JSON), domain, endpointId, tier, fromCache }`
  81. **Example:**
  82. ```
  83. # Get live stock quote (Robinhood, no auth needed)
  84. apitap_replay("api.robinhood.com", "get-marketdata-quotes", { symbols: "TSLA,MSFT" })
  85. # Get NBA scores (ESPN)
  86. apitap_replay("site.api.espn.com", "get-apis-personalized-v2-scoreboard-header")
  87. # Get crypto trending (CoinMarketCap)
  88. apitap_replay("api.coinmarketcap.com", "get-data-api-v3-unified-trending-top-boost-listing")
  89. ```
  90. #### `apitap_replay_batch`
  91. Replay multiple endpoints in one call.
  92. ```
  93. apitap_replay_batch(requests: Array<{ domain, endpointId, endpointParams? }>, maxBytes?: number)
  94. ```
  95. ### Tier 3: Capture (15-20K tokens, uses browser)
  96. #### `apitap_capture`
  97. Launch a headless browser to capture API traffic from a website.
  98. ```
  99. apitap_capture(url: string, duration?: number) → { sessionId }
  100. ```
  101. **Use when:** No skill file exists and `apitap_read` doesn't give you the data you need. This is expensive but creates a skill file for future free replays.
  102. #### `apitap_capture_interact`
  103. Send browser commands during an active capture session.
  104. ```
  105. apitap_capture_interact(sessionId: string, action: string, ...) → result
  106. ```
  107. Actions: `click`, `type`, `navigate`, `snapshot`, `scroll`, `wait`
  108. #### `apitap_capture_finish`
  109. End capture session, generate skill file, verify endpoints.
  110. ```
  111. apitap_capture_finish(sessionId: string) → { skillFile, endpoints[] }
  112. ```
  113. ### Auto-Router
  114. #### `apitap_browse`
  115. Automatic escalation: cache → skill file → discover → **read** → capture_needed.
  116. ```
  117. apitap_browse(url: string, query?: string, maxBytes?: number) → result
  118. ```
  119. **Use when:** You don't know which tier to use. This tries the cheapest option first and escalates automatically.
  120. ### Inspection
  121. #### `apitap_inspect`
  122. Get details about a skill file's endpoints.
  123. ```
  124. apitap_inspect(domain: string) → { endpoints[], metadata }
  125. ```
  126. #### `apitap_stats`
  127. Usage statistics across all skill files.
  128. ```
  129. apitap_stats() → { domains, endpoints, tiers }
  130. ```
  131. ## Decision Tree
  132. ```
  133. Need web data?
  134. │
  135. ├─ Know the domain? → apitap_search → found? → apitap_replay (cheapest)
  136. │
  137. ├─ Unknown URL → apitap_peek first (free)
  138. │ ├─ recommendation: "blocked" → STOP, tell user
  139. │ ├─ recommendation: "read" → apitap_read (no browser)
  140. │ ├─ recommendation: "capture" → apitap_capture (browser)
  141. │ ├─ recommendation: "auth_required" → needs human login
  142. │ └─ recommendation: "not_found" → STOP, the page does not exist (404/410)
  143. │
  144. ├─ Just need article/post content → apitap_read directly
  145. │
  146. └─ Need structured API data → apitap_capture → creates skill file → future replays free
  147. ```
  148. ## Key Patterns
  149. ### Instagram profile data (login wall bypass)
  150. Instagram blocks all normal scraping (Googlebot UA, oembed, noembed). But the **mobile API** works:
  151. ```bash
  152. curl -s 'https://i.instagram.com/api/v1/users/web_profile_info/?params={"user_name":"TARGET_USERNAME"}' \
  153. -H 'User-Agent: Instagram 275.0.0.27.98 Android (33/13; 420dpi; 1080x2400; samsung; SM-G991B; o1s; exynos2100)' \
  154. -H 'X-IG-App-ID: 936619743392459'
  155. ```
  156. **Returns:** Full profile JSON — bio, follower/following counts, post count, contact info (email, phone), category, highlights, recent posts with captions/engagement.
  157. **When to use:** Need Instagram profile data, follower counts, contact info, or recent post summaries. Works without auth.
  158. **Limitations:** Only public profiles. Rate-limited if abused. Does NOT return full post feeds — just recent edge.
  159. ### Morning news scan
  160. ```
  161. # Scan multiple subreddits
  162. for sub in ["technology", "wallstreetbets", "privacy"]:
  163. apitap_read(f"https://www.reddit.com/r/{sub}")
  164. ```
  165. ### Stock research
  166. ```
  167. # Live quote via captured API
  168. apitap_replay("api.robinhood.com", "get-marketdata-quotes", { symbols: "TSLA" })
  169. # Company fundamentals
  170. apitap_replay("api.robinhood.com", "get-fundamentals", { symbol: "TSLA" })
  171. ```
  172. ### Research any topic (dual knowledge base)
  173. ```
  174. # 1. Read Wikipedia summary (established knowledge)
  175. apitap_read("https://en.wikipedia.org/wiki/Topic")
  176. # 2. Read Grokipedia article (AI-curated, with citations)
  177. apitap_read("https://grokipedia.com/wiki/Topic")
  178. # 3. Check Reddit discussion (community sentiment)
  179. apitap_read("https://www.reddit.com/r/relevant_sub")
  180. # 4. Read a linked article
  181. apitap_read("https://news-site.com/article")
  182. ```
  183. ### Check before committing
  184. ```
  185. # Peek first — is it worth reading?
  186. result = apitap_peek("https://some-site.com")
  187. if result.recommendation == "read":
  188. apitap_read("https://some-site.com")
  189. elif result.recommendation == "blocked":
  190. # Don't waste tokens
  191. pass
  192. ```
  193. ## Token Economics
  194. | Method | Cost per page | Notes |
  195. |--------|-------------|-------|
  196. | Browser automation | 50-200K tokens | Full DOM serialization |
  197. | apitap_read | 0-10K tokens | No browser, side channels |
  198. | apitap_replay | 1-5K tokens | Direct API call, needs skill file |
  199. | apitap_peek | ~0 tokens | HEAD request only |
  200. ## CLI Usage
  201. All MCP tools are also available as CLI commands:
  202. ```bash
  203. apitap peek <url> [--json]
  204. apitap read <url> [--json] [--max-bytes <n>]
  205. apitap search <query> [--json]
  206. apitap replay <domain> <endpointId> [--params '{}'] [--json]
  207. apitap capture <url> [--duration <sec>] [--json]
  208. apitap inspect <domain> [--json]
  209. apitap stats [--json]
  210. ```
  211. Every command supports `--json` for machine-readable output.
README.md · README · 775 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # ApiTap
  2. [![npm version](https://img.shields.io/npm/v/@apitap/core)](https://www.npmjs.com/package/@apitap/core)
  3. [![tests](https://img.shields.io/badge/tests-1976%20passing-brightgreen)](https://github.com/n1byn1kt/apitap)
  4. [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
  5. **The CLI, MCP server, and npm library that turns any website into an API — no docs, no SDK, no browser.**
  6. ApiTap is a CLI, MCP server, and npm library that lets AI agents (and you) browse the web through APIs instead of browsers. Point it at a site: it captures the internal API from real traffic, generates a portable signed **skill file**, and replays requests directly with `fetch()`. Credentials never live in the file — they stay in encrypted storage and are injected at replay — and replays are matched against the captured route shapes, so your agent learns an endpoint drifted *before* it fails mid-task. No DOM, no selectors, no flaky waits. Token costs drop 20-100x compared to browser automation. Sites that publish OpenAPI specs can skip capture entirely via `apitap import` (APIs.guru directory built in).
  7. The web was built for human eyes; ApiTap makes it native to machines.
  8. ```bash
  9. # Capture a site's private API once…
  10. apitap capture https://polymarket.com
  11. # …then replay it forever — no browser in this path
  12. apitap replay gamma-api.polymarket.com get-events
  13. # Read page content without a browser
  14. apitap read https://en.wikipedia.org/wiki/Node.js
  15. ✓ Wikipedia decoder: ~127 tokens (vs ~4,900 raw HTML)
  16. # Or import published OpenAPI specs directly
  17. apitap import --from apis-guru --search stripe
  18. apitap replay api.stripe.com get-listcharges limit=5
  19. ```
  20. No scraping. No browser. Just the API.
  21. ![ApiTap demo](https://raw.githubusercontent.com/n1byn1kt/apitap/main/docs/demo.gif)
  22. ---
  23. ## How It Works
  24. ApiTap has three ways to build its API knowledge:
  25. 1. **Capture** (30 seconds) — Launch a browser, visit a site, browse normally. ApiTap intercepts all network traffic via CDP, filters noise, and generates a skill file. Or use `apitap attach` to capture from your already-running Chrome.
  26. 2. **Discover** (automatic) — ApiTap auto-detects frameworks (WordPress, Next.js, Shopify) and probes for OpenAPI specs at common paths. Works without a browser.
  27. 3. **Import** (instant) — Import OpenAPI/Swagger specs from the [APIs.guru](https://apis.guru) directory of 2,500+ public APIs, or from any spec URL/file. Endpoints get a confidence score based on spec quality. No browser needed.
  28. All three paths produce the same artifact: a **skill file** — a portable JSON map of an API's endpoints, stored at `~/.apitap/skills/`.
  29. ```
  30. Import: OpenAPI spec → Converter → Merge → skill.json (confidence 0.6-0.85)
  31. Capture: Browser → CDP listener → Filter → Skill Generator → skill.json (confidence 1.0)
  32. Attach: Running Chrome → CDP attach → Filter → skill.json (confidence 0.8-1.0)
  33. Replay: Agent → Replay Engine (skill.json) → fetch() → API → JSON response
  34. ↑ no browser in this path
  35. ```
  36. ### Confidence Model
  37. Every endpoint tracks how it was discovered:
  38. | Source | Confidence | Meaning |
  39. |--------|-----------|---------|
  40. | Captured with response body | 1.0 | Full capture — response shape verified |
  41. | OpenAPI import, high quality | 0.85 | Spec has response examples |
  42. | CDP skeleton (real traffic, no body) | 0.8 | Endpoint exists, body was evicted from Chrome buffer |
  43. | OpenAPI import, base | 0.6 | Thin spec, no examples |
  44. Imported endpoints auto-upgrade to confidence 1.0 on first successful replay. The merge is additive — captured data is never overwritten by imports, imports fill gaps that capture missed.
  45. ## Install
  46. ```bash
  47. npm install -g @apitap/core
  48. ```
  49. **Claude Code** — one command to wire it up:
  50. ```bash
  51. claude mcp add -s user apitap -- apitap mcp
  52. ```
  53. That's it. 12 MCP tools, ready to go. Requires Node.js 20+.
  54. > **Note:** `npx @apitap/core mcp` does not work due to [npm scoped package bin resolution](https://github.com/n1byn1kt/apitap/issues/46). Use `npx apitap mcp` or `apitap-mcp` instead.
  55. > **Optional:** To use `capture` and `browse` (which open a real browser), also run:
  56. > ```bash
  57. > npx playwright install chromium
  58. > ```
  59. > The `read`, `peek`, `discover`, and `import` tools work without it.
  60. ## Use with Hermes
  61. [Hermes Agent](https://github.com/NousResearch/hermes-agent) users can install ApiTap as a skill:
  62. ```bash
  63. hermes skills install n1byn1kt/apitap/skills/hermes/apitap
  64. ```
  65. Or straight from the raw file:
  66. ```bash
  67. hermes skills install https://raw.githubusercontent.com/n1byn1kt/apitap/main/skills/hermes/apitap/SKILL.md
  68. ```
  69. The skill drives the `apitap` CLI through Hermes' `terminal` toolset, so it
  70. needs `npm install -g @apitap/core` on the machine running Hermes. Once
  71. installed it is also a slash command: `/apitap read <url>`.
  72. For heavy use, wire the MCP server into `config.yaml` instead — the skill's
  73. last section has the block.
  74. ## Quick Start
  75. ### Import APIs instantly
  76. ```bash
  77. # Import from the APIs.guru directory (2,500+ public APIs)
  78. apitap import --from apis-guru --limit 100
  79. # Import a specific API by name
  80. apitap import --from apis-guru --search stripe
  81. # Import a single OpenAPI spec from URL
  82. apitap import https://api.apis.guru/v2/specs/stripe.com/2022-11-15/openapi.json
  83. # Import a local spec file (JSON or YAML)
  84. apitap import ./my-api-spec.json
  85. # Skip auth-required APIs (open endpoints only)
  86. apitap import --from apis-guru --limit 500 --no-auth-only
  87. # Preview what would be imported
  88. apitap import --from apis-guru --search twilio --dry-run
  89. # Update previously imported APIs (skip unchanged)
  90. apitap import --from apis-guru --update
  91. ```
  92. Import produces a diff showing what changed:
  93. ```
  94. Importing api.stripe.com from OpenAPI 3.0 spec...
  95. ✓ 12 existing captured endpoints preserved
  96. + 34 new endpoints added from OpenAPI spec
  97. ~ 8 endpoints enriched with spec metadata
  98. · 0 skipped (already imported)
  99. Skill file: ~/.apitap/skills/api.stripe.com.json (54 endpoints)
  100. ```
  101. Captured endpoints are never overwritten. Import fills gaps and adds metadata (descriptions, response schemas, query param enums) from the spec.
  102. ### Capture API traffic
  103. ```bash
  104. # Capture from a single domain (default)
  105. apitap capture https://polymarket.com
  106. # Capture all domains (CDN, API subdomains, etc.)
  107. apitap capture https://polymarket.com --all-domains
  108. # Include response previews in the skill file
  109. apitap capture https://polymarket.com --preview
  110. # Stop after 30 seconds
  111. apitap capture https://polymarket.com --duration 30
  112. ```
  113. ApiTap opens a browser window. Browse the site normally — click around, scroll, search. Every API call is captured. Press Ctrl+C when done.
  114. ### Attach to a running Chrome
  115. ```bash
  116. # Launch Chrome with remote debugging enabled
  117. google-chrome --remote-debugging-port=9222
  118. # Attach to your signed-in Chrome — captures all tabs
  119. apitap attach --port 9222
  120. # Filter to specific domains
  121. apitap attach --port 9222 --domain *.github.com
  122. # Ctrl+C to stop — generates signed skill files for each captured domain
  123. ```
  124. No separate browser, no re-login. Captures from your real Chrome sessions with all your cookies and auth tokens. When response bodies are evicted from Chrome's buffer (common on high-traffic pages), skeleton endpoints are written at confidence 0.8 instead of being dropped.
  125. ### List and explore APIs
  126. ```bash
  127. # List all skill files
  128. apitap list
  129. ✓ api.stripe.com 446 endpoints 5m ago [imported-signed]
  130. ✓ gamma-api.polymarket.com 3 endpoints 2h ago [signed]
  131. ✓ api.github.com 499 endpoints 1h ago [imported-signed]
  132. # Show endpoints for a domain
  133. apitap show api.stripe.com
  134. [ ] GET /v1/account object (22 fields)
  135. [ ] GET /v1/charges object (4 fields)
  136. [ ] GET /v1/customers/:customer object (30 fields)
  137. # Search across all skill files
  138. apitap search stripe
  139. ```
  140. ### Replay an endpoint
  141. ```bash
  142. # Replay with captured defaults
  143. apitap replay gamma-api.polymarket.com get-events
  144. # Override parameters
  145. apitap replay gamma-api.polymarket.com get-events limit=5 offset=10
  146. # Machine-readable JSON output
  147. apitap replay gamma-api.polymarket.com get-events --json
  148. ```
  149. ## Text-Mode Browsing
  150. ApiTap includes a text-mode browsing pipeline — `peek` and `read` — that lets agents consume web content without launching a browser. Seven built-in decoders extract structured content from popular sites at a fraction of the token cost:
  151. | Site | Decoder | Typical Tokens | vs Raw HTML |
  152. |------|---------|----------------|-------------|
  153. | Reddit | `reddit` | ~627 | 93% smaller |
  154. | YouTube | `youtube` | ~36 | 99% smaller |
  155. | Wikipedia | `wikipedia` | ~127 | 97% smaller |
  156. | Hacker News | `hackernews` | ~200 | 90% smaller |
  157. | Grokipedia | `grokipedia` | ~150-5000+ | varies by article length |
  158. | Twitter/X | `twitter` | ~80 | 95% smaller |
  159. | Any other site | `generic` | varies | ~74% avg |
  160. **Average token savings: 74% across 83 tested domains.**
  161. ```bash
  162. # Triage first — zero-cost HEAD request
  163. apitap peek https://reddit.com/r/programming
  164. ✓ accessible, recommendation: read
  165. # Extract content — no browser needed
  166. apitap read https://reddit.com/r/programming
  167. ✓ Reddit decoder: 12 posts, ~627 tokens
  168. # Works for any URL — falls back to generic HTML extraction
  169. apitap read https://example.com/blog/post
  170. ```
  171. For MCP agents, `apitap_peek` and `apitap_read` are the fastest way to consume web content — use them before reaching for `apitap_browse` or `apitap_capture`.
  172. ### Bounding response size with `--max-bytes`
  173. `--max-bytes` (MCP: `maxBytes`) is a **hard cap on the full serialized response envelope**, not just on the data or content field. It applies uniformly across `apitap replay`, `apitap browse`, and `apitap read` (including every built-in decoder — Wikipedia, Hacker News, Reddit, etc.), so a bounded call returns a bounded envelope no matter which path served it.
  174. ```bash
  175. apitap replay gamma-api.polymarket.com get-events --json --max-bytes 4000
  176. apitap read https://en.wikipedia.org/wiki/Node.js --max-bytes 4000
  177. ```
  178. How the cap is honoured:
  179. - **Read path** — links are shrunk first (deduped, then halved), then content is re-sliced byte-accurately. When content is cut, the envelope carries `contentTruncated: true` so the truncation is never silent.
  180. - **Replay path** — the data payload is trimmed to fit under the same budget, flooring at a **512-byte data minimum** so a pathologically small `--max-bytes` still returns usable data (the only documented case where the envelope may exceed the cap). Concretely: a dense real-world payload replayed at `--max-bytes 4000` can land around 4.5–4.7 KB — irreducible smallest item plus the never-dropped envelope skeleton — and that is the floor working as designed, not a leak.
  181. - **`envelopeBytes`** — every capped response reports its own actual serialized size in bytes. It is recorded after the diet runs, so `envelopeBytes ≤ maxBytes` (within a few bytes of fixed-width measurement slack), except in the floor case above where irreducible data plus never-dropped metadata can honestly exceed the budget. Use it to see how much of the budget a response actually consumed.
  182. ## Pre-Loaded APIs
  183. ApiTap can instantly import from the [APIs.guru](https://apis.guru) directory of 2,500+ public API specs. A single command populates your local pattern database:
  184. ```bash
  185. apitap import --from apis-guru --limit 500
  186. ```
  187. Some of the APIs available out of the box:
  188. | API | Endpoints | Auth |
  189. |-----|-----------|------|
  190. | Stripe | 446 | API Key |
  191. | GitHub | 499 | OAuth |
  192. | Jira/Atlassian | 487 | API Key |
  193. | Twilio | 199+ | API Key |
  194. | Slack | 175 | OAuth |
  195. | DigitalOcean | 290 | Bearer |
  196. | Linode | 350 | Bearer |
  197. | SendGrid | 334 | API Key |
  198. | Spotify | 90 | OAuth |
  199. | Square | 200 | OAuth |
  200. | Plaid | 198 | API Key |
  201. | Asana | 167 | Bearer |
  202. | Twitter | 163 | OAuth |
  203. | Vimeo | 326 | OAuth |
  204. | OpenAI | 28 | API Key |
  205. Auth-required APIs import as endpoint maps with response schemas — you can explore what's available and see response shapes before setting up credentials. First successful replay with real auth auto-upgrades the endpoint to full captured status.
  206. ## Why ApiTap?
  207. **Why not just use the public API?** Most sites don't have one, or it's heavily rate-limited. The internal API that powers the SPA is often richer, faster, and already handles auth.
  208. **Why not just use Playwright/Puppeteer?** Browser automation costs 50-200K tokens per page for an AI agent. ApiTap captures the API once, then your agent calls it directly at 1-5K tokens. No DOM, no selectors, no flaky waits.
  209. **Why not reverse-engineer the API manually?** You could open DevTools and copy headers by hand. ApiTap does it in 30 seconds and gives you a portable file any agent can use.
  210. **Why not just use an OpenAPI spec?** You can! `apitap import` converts OpenAPI/Swagger specs directly into skill files. But many sites don't publish specs — ApiTap captures their APIs from live traffic.
  211. **Isn't this just a MITM proxy?** No. ApiTap is read-only — it uses Chrome DevTools Protocol to observe responses. No certificate setup, no request modification, no code injection.
  212. **Why trust a client derived from captured traffic?** Because ApiTap treats trust as the product: skill files are HMAC-signed, credentials never enter them (encrypted separately, injected at replay time), replays are matched against the captured route templates instead of "close enough" URLs, and every endpoint carries a replayability tier. When a response stops matching what was captured, ApiTap says so — instead of handing your agent plausible-but-wrong data. Compare that to pasting a raw HAR (bearer tokens included) into an LLM context.
  213. ## Replayability Tiers
  214. Every captured endpoint is classified by replay difficulty:
  215. | Tier | Meaning | Replay |
  216. |------|---------|--------|
  217. | **Green** | Public, permissive CORS, no signing | Works with `fetch()` |
  218. | **Yellow** | Needs auth, no signing/anti-bot | Works with stored credentials |
  219. | **Orange** | CSRF tokens, session binding | Fragile — may need browser refresh |
  220. | **Red** | Request signing, anti-bot (Cloudflare) | Needs full browser |
  221. GET endpoints are auto-verified during capture by comparing Playwright responses with raw `fetch()` responses.
  222. ## MCP Server
  223. ApiTap includes an MCP server with 12 tools for Claude Desktop, Cursor, Windsurf, and other MCP-compatible clients.
  224. ```bash
  225. # Start the MCP server
  226. apitap mcp
  227. # Also works via npx (no global install needed)
  228. npx apitap mcp
  229. ```
  230. > The legacy `apitap-mcp` binary still works but `apitap mcp` is preferred.
  231. > `npx @apitap/core mcp` does **not** work — npm can't resolve the default bin for scoped packages with multiple bins ([#46](https://github.com/n1byn1kt/apitap/issues/46)).
  232. **Claude Code** — see [Install](#install) above.
  233. **Claude Desktop / Cursor / Windsurf** — add to your MCP config:
  234. ```json
  235. {
  236. "mcpServers": {
  237. "apitap": {
  238. "command": "apitap",
  239. "args": ["mcp"]
  240. }
  241. }
  242. }
  243. ```
  244. **VS Code (GitHub Copilot)** — add `.vscode/mcp.json`:
  245. ```json
  246. {
  247. "servers": {
  248. "apitap": {
  249. "command": "apitap",
  250. "args": ["mcp"]
  251. }
  252. }
  253. }
  254. ```
  255. ### MCP Tools
  256. | Tool | Description |
  257. |------|-------------|
  258. | `apitap_browse` | High-level "just get me the data" (discover + replay in one call) |
  259. | `apitap_peek` | Zero-cost URL triage (HEAD only) |
  260. | `apitap_read` | Extract content without a browser (7 decoders) |
  261. | `apitap_discover` | Detect a site's APIs without launching a browser |
  262. | `apitap_search` | Search available skill files |
  263. | `apitap_replay` | Replay a captured API endpoint |
  264. | `apitap_replay_batch` | Replay multiple endpoints in parallel across domains |
  265. | `apitap_capture` | Capture API traffic via instrumented browser |
  266. | `apitap_capture_start` | Start an interactive capture session |
  267. | `apitap_capture_interact` | Interact with a live capture session (click, type, scroll) |
  268. | `apitap_capture_finish` | Finish or abort a capture session |
  269. | `apitap_auth_request` | Request human authentication for a site |
  270. You can also serve a single skill file as a dedicated MCP server with `apitap serve <domain>` — each endpoint becomes its own tool.
  271. ## Chrome Extension
  272. > **Optional.** ApiTap works fully without the extension. Install it if you want passive API discovery or want to capture from your already-logged-in browser sessions.
  273. The extension captures API traffic directly from your browser — no Playwright, no auth dance, no browser popups. It also silently builds a map of every API you visit in the background.
  274. **Why use the extension?**
  275. - You're already logged into Spotify, Discord, Reddit — the extension captures from your live session
  276. - No `apitap auth request` needed — real tokens are captured automatically
  277. - Passively builds a map of every API you visit, so your agents know what's available before asking
  278. ### Setup
  279. **Step 1 — Install ApiTap CLI** (if you haven't already):
  280. ```bash
  281. npm install -g @apitap/core
  282. ```
  283. **Step 2 — Get the extension source:**
  284. ```bash
  285. git clone https://github.com/n1byn1kt/apitap.git
  286. cd apitap
  287. ```
  288. **Step 3 — Build the extension:**
  289. ```bash
  290. cd extension && npm install && npm run build
  291. ```
  292. **Step 4 — Load into Chrome:**
  293. 1. Open `chrome://extensions`
  294. 2. Enable **Developer mode** (toggle, top right)
  295. 3. Click **Load unpacked**
  296. 4. Select the `extension/` folder inside the cloned repo
  297. You should see the ApiTap icon appear in your toolbar.
  298. **Step 5 — Wire up native messaging (one-time):**
  299. ```bash
  300. apitap extension install --extension-id <your-extension-id>
  301. ```
  302. Find your extension ID on the `chrome://extensions` page (shown under the extension name after loading).
  303. **Step 6 — Verify the connection:**
  304. Click the ApiTap icon in Chrome. The popup should show **"CLI: Connected"**. If it shows disconnected, re-run Step 5 with the correct extension ID.
  305. ### Passive Index (always-on)
  306. Once installed, the extension silently observes API traffic as you browse — no infobar, no CDP, no performance impact. It builds a lightweight index of every domain's API shape: endpoints, HTTP methods, auth type, pagination patterns.
  307. ```bash
  308. # See everything the extension has discovered
  309. apitap index
  310. # Filter to a specific domain
  311. apitap index discord.com
  312. ```
  313. The index lives at `~/.apitap/index.json` and is automatically read by the `apitap_discover` MCP tool — so your agents can ask "what do you know about Discord's API?" and get a useful answer without triggering a full capture.
  314. ### Promoting to a Full Skill File
  315. The index is a map — it knows what endpoints exist but not their response shapes. To get a full replayable skill file, promote a domain:
  316. **From the popup:** Click the ApiTap icon -> find the domain -> **Generate skill file**
  317. **Via agent:** Your agent can request a capture automatically. You'll get a notification to approve, the extension briefly attaches CDP, captures response shapes, then detaches. The full skill file saves to `~/.apitap/skills/`.
  318. **Auto-learn (opt-in):** In the extension popup -> Settings -> enable **Auto-learn**. The extension will automatically promote domains you visit frequently. Off by default.
  319. ### Manual Capture
  320. For one-off captures without the passive index:
  321. 1. Click the ApiTap icon -> **Start Capture**
  322. 2. Browse the site — extension records API traffic
  323. 3. Click **Stop** -> skill file auto-saves to `~/.apitap/skills/`
  324. The popup shows CLI connection status and live capture stats. Auth tokens are encrypted with AES-256-GCM in session storage and automatically persisted to `~/.apitap/auth.enc` via the native host, with `[stored]` placeholders in the exported skill files.
  325. > **Note:** Chrome Web Store submission coming soon. For now, load as an unpacked extension in Developer mode.
  326. ---
  327. ## Auth Management
  328. ApiTap automatically detects and stores auth credentials (Bearer tokens, API keys, cookies) during capture. Credentials are encrypted at rest with AES-256-GCM.
  329. ```bash
  330. # View auth status
  331. apitap auth api.example.com
  332. # List all domains with stored auth
  333. apitap auth --list
  334. # Open a browser so a human can sign in, then store the session
  335. # (close the browser window when done — that is the "finished" signal)
  336. apitap auth request api.example.com
  337. # Refresh expired tokens via browser
  338. apitap refresh api.example.com
  339. # Force fresh token before replay
  340. apitap replay api.example.com get-data --fresh
  341. # Clear stored auth
  342. apitap auth api.example.com --clear
  343. ```
  344. ## Skill Files
  345. Skill files are JSON documents stored at `~/.apitap/skills/<domain>.json`. They contain everything needed to replay an API — endpoints, headers, query params, request bodies, pagination patterns, and response shapes.
  346. ```json
  347. {
  348. "version": "1.2",
  349. "domain": "gamma-api.polymarket.com",
  350. "baseUrl": "https://gamma-api.polymarket.com",
  351. "endpoints": [
  352. {
  353. "id": "get-events",
  354. "method": "GET",
  355. "path": "/events",
  356. "queryParams": { "limit": { "type": "string", "example": "10" } },
  357. "headers": {},
  358. "responseShape": { "type": "object", "fields": ["id", "title", "slug"] },
  359. "confidence": 1.0,
  360. "endpointProvenance": "captured"
  361. }
  362. ]
  363. }
  364. ```
  365. Skill files are portable and shareable. Auth credentials are stored separately in encrypted storage — never in the skill file itself.
  366. ### Import / Export
  367. ```bash
  368. # Import a skill file from someone else
  369. apitap import ./reddit-skills.json
  370. # Import an OpenAPI spec (JSON or YAML)
  371. apitap import ./stripe-openapi.json
  372. apitap import https://api.apis.guru/v2/specs/stripe.com/2022-11-15/openapi.json
  373. # Import validates: signature check / SSRF scan / format detection / confirmation
  374. ```
  375. Imported files are re-signed with your local key. OpenAPI specs are automatically detected and converted using the same merge logic — captured endpoints are preserved, imports fill gaps.
  376. ### apitap doctor
  377. Offline hygiene check for your skill store — finds junk domains (ad/WAF/consent
  378. hosts), tracker beacon endpoints inside good skills, duplicate endpoints, stale
  379. captures, never-verified endpoints, and unsigned/tampered files.
  380. apitap doctor # report only; exit 1 if findings
  381. apitap doctor --fix # apply conservative fixes (quarantine + snapshot)
  382. apitap doctor --restore example.com # undo
  383. apitap doctor --json # machine-readable report
  384. `--fix` never deletes: whole files move to `~/.apitap/skills/.quarantine/`,
  385. edited files keep a first-touch original under `~/.apitap/skills/.doctor/`.
  386. Files whose signature does not verify are reported but never edited.
  387. ## Security
  388. ApiTap handles untrusted skill files from the internet and replays HTTP requests on your behalf. That's a high-trust position, and we treat it seriously.
  389. ### Defense in Depth
  390. - **Auth encryption** — AES-256-GCM with PBKDF2 key derivation, keyed to your machine
  391. - **PII scrubbing** — Emails, phones, IPs, credit cards, SSNs detected and redacted during capture
  392. - **SSRF protection** — Multi-layer URL validation blocks access to internal networks (see below)
  393. - **Header injection protection** — Allowlist prevents skill files from injecting dangerous HTTP headers (`Host`, `X-Forwarded-For`, `Cookie`, `Authorization`)
  394. - **Redirect validation** — Manual redirect handling with SSRF re-check prevents redirect-to-internal-IP attacks
  395. - **DNS rebinding prevention** — Resolved IPs are pinned to prevent TOCTOU attacks where DNS returns different IPs on second lookup
  396. - **Skill signing** — HMAC-SHA256 signatures detect tampering; four-state provenance tracking (self/imported/imported-signed/unsigned)
  397. - **Atomic writes** — Skill files are written to a temp file then renamed, preventing corruption from mid-write crashes
  398. - **Safe JSON parsing** — Server responses parsed with `safeParseJson()` that returns raw text on malformed JSON instead of crashing
  399. - **Spec fetch hardening** — OpenAPI spec imports are SSRF-validated, size-limited (10MB), timeout-limited (30s), and reject redirects
  400. - **External $ref rejection** — Only local document `#/` references are resolved; `file://` and remote `$ref` pointers are blocked
  401. - **No phone-home** — Everything runs locally. No external services, no telemetry
  402. - **Read-only capture** — Playwright intercepts responses only. No request modification or code injection
  403. ### Why SSRF Protection Matters
  404. Since skill files can come from anywhere — shared by colleagues, downloaded from GitHub, or imported from untrusted sources — a malicious skill file is the primary threat vector. Here's what ApiTap defends against:
  405. **The attack:** An attacker crafts a skill file with `baseUrl: "http://169.254.169.254"` (the AWS/cloud metadata endpoint) or `baseUrl: "http://localhost:8080"` (your internal services). When you replay an endpoint, your machine makes the request, potentially leaking cloud credentials or hitting internal APIs.
  406. **The defense:** ApiTap validates every URL at multiple points:
  407. ```
  408. Skill file imported
  409. -> validateUrl(): block private IPs, internal hostnames, non-HTTP schemes
  410. -> validateSkillFileUrls(): scan baseUrl + all endpoint example URLs
  411. OpenAPI spec imported
  412. -> resolveAndValidateUrl(): SSRF check on spec URL before fetching
  413. -> resolveAndValidateUrl(): SSRF check on extracted API domain
  414. -> validateSkillFile(): validate merged skill file before writing
  415. Endpoint replayed
  416. -> resolveAndValidateUrl(): DNS lookup + verify resolved IP isn't private
  417. -> IP pinning: fetch uses resolved IP directly (prevents DNS rebinding)
  418. -> Header filtering: strip dangerous headers from skill file
  419. -> Redirect check: if server redirects, validate new target before following
  420. ```
  421. **Blocked ranges:** `127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `169.254.0.0/16` (cloud metadata), `100.64.0.0/10` (CGNAT/Tailscale), `198.18.0.0/15` (benchmarking), `240.0.0.0/4` (reserved), `0.0.0.0`, IPv6 equivalents (`::1`, `fe80::/10`, `fc00::/7`, `::ffff:` mapped addresses), `localhost`, `.local`, `.internal`, `file://`, `javascript:` schemes. Alternative IP representations (decimal integer, octal, hex) are normalized before checking.
  422. This is especially relevant now that [MCP servers are being used as attack vectors in the wild](https://cloud.google.com/blog/topics/threat-intelligence/distillation-experimentation-integration-ai-adversarial-use) — Google's Threat Intelligence Group recently documented underground toolkits built on compromised MCP servers. ApiTap is designed to be safe even when processing untrusted inputs.
  423. ## Trap-Aware Mode
  424. ApiTap ingests web content on behalf of agents, and adds inspection at the two places it already sits in the pipeline:
  425. - **`apitap read`** scans raw HTML for hidden content containing explicit prompt-injection markers before extraction. Results are annotated on the response via a `findings[]` field; content is never modified.
  426. - **`apitap replay`** optionally scans outbound request bodies and query strings for secret patterns (SSH keys, cloud credentials, API tokens) before the `fetch()` call. Opt-in per skill file or globally.
  427. ### Read-side scanner
  428. The read scanner runs by default on `apitap read` and the `apitap_read` MCP tool. It uses a two-condition gate: a finding is emitted only when content is in a hidden position (inline `style:display:none`, `visibility:hidden`, `opacity:0`, off-viewport positioning, `hidden` attribute, `aria-hidden="true"`, or inside an HTML comment) **and** the hidden content matches an explicit role marker or a known prompt-injection signature.
  429. Visible content never triggers a finding. Blog posts about prompt engineering, documentation of jailbreak techniques, and this README itself are all non-triggering.
  430. Disable with `--no-scan` on the CLI or `scan: false` on the MCP tool.
  431. ```bash
  432. apitap read https://example.com # scan on by default
  433. apitap read https://example.com --no-scan # scan off
  434. ```
  435. **Known limitations:**
  436. - Class-based CSS hiding is not detected in v1.0. The generic HTML extractor strips `<style>` blocks before the scanner runs, so class-resolved hiding is invisible.
  437. - Site-specific decoders (Reddit, YouTube, Wikipedia, HN, Twitter, Grokipedia, DeepWiki) bypass scanning. They extract from structured API sources rather than raw HTML.
  438. - The scanner is a heuristic, not a classifier. Absence of findings is not proof of safety.
  439. ### Egress-side scanner (opt-in)
  440. The egress scanner is **opt-in per domain** or globally. Default behavior on upgrade is byte-identical to the previous release — cron-job users see zero change unless they explicitly enable it.
  441. Three ways to enable:
  442. **Per skill file** — add `egress_check: true` to the skill file (part of the signed payload):
  443. ```json
  444. {
  445. "version": "1.2",
  446. "domain": "api.example.com",
  447. "egress_check": true,
  448. "egress_action": "annotate",
  449. "endpoints": []
  450. }
  451. ```
  452. **Globally** — via `$XDG_CONFIG_HOME/apitap/config.json`:
  453. ```json
  454. {
  455. "egressCheckAll": true,
  456. "egressCheckAction": "annotate"
  457. }
  458. ```
  459. **Per call** — via the CLI flag or MCP tool argument:
  460. ```bash
  461. apitap replay api.example.com post-submit --egress-check=annotate
  462. apitap replay api.example.com post-submit --egress-check=block
  463. apitap replay api.example.com post-submit --no-egress-check
  464. ```
  465. Precedence: per-call → skill file → global config → off.
  466. When enabled with `annotate` (default action), the request proceeds normally and the response envelope gains a `warnings[]` field. When enabled with `block`, `high`-severity findings refuse the request. `medium`-severity findings (PII) always annotate, never block.
  467. ### Audit log
  468. Both scanners write findings to `$XDG_STATE_HOME/apitap/findings.jsonl` (default: `~/.local/state/apitap/findings.jsonl`):
  469. ```bash
  470. apitap audit --findings
  471. apitap audit --findings --source=egress --since=2026-04-01
  472. apitap audit --findings --json
  473. ```
  474. The audit log **never contains matched secret bytes**. Egress findings record pattern name, parameter location, structural path, and match length only.
  475. ### Honest threat model
  476. - The read scanner catches hidden content with explicit prompt-injection markers. It does not catch semantic manipulation, framing attacks, class-based hidden content, font-face remapping, or content hidden via external stylesheets.
  477. - The egress scanner uses pattern matching. An attacker who can get the agent to encode or transform a secret before sending it will defeat pattern matching. This is defense in depth, not a DLP solution.
  478. - The audit log is advisory tamper-evidence, same-user boundary. Same threat model as ApiTap's existing skill signing.
  479. - v1.0 is rules-based. No learning loop. Tuning happens via signature list updates informed by audit log data.
  480. ## CLI Reference
  481. All commands support `--json` for machine-readable output.
  482. On failure, `--json` prints a parseable envelope on stdout and exits non-zero:
  483. ```json
  484. {
  485. "success": false,
  486. "error": "Domain required",
  487. "usage": "apitap show <domain>"
  488. }
  489. ```
  490. Longer guidance, where a command has any, arrives in an optional `hint` field
  491. rather than inside `error`, so an agent can surface the defect on its own.
  492. The human-readable line still goes to stderr, so interactive use is unchanged
  493. and `apitap … --json > out.json` captures only the envelope. `apitap serve` is
  494. the one channel exception: its stdout is the MCP stdio transport, so its failure
  495. envelope goes to stderr alongside its `--json` tool list — and there the human
  496. line is suppressed, so `JSON.parse` of serve's stderr succeeds.
  497. | Command | Description |
  498. |---------|-------------|
  499. | `apitap browse <url>` | Discover + replay in one step |
  500. | `apitap peek <url>` | Zero-cost URL triage (HEAD only) |
  501. | `apitap read <url>` | Extract content without a browser |
  502. | `apitap discover <url>` | Detect APIs without launching a browser |
  503. | `apitap capture <url>` | Capture API traffic from a website |
  504. | `apitap attach --port <port>` | Attach to running Chrome and capture API traffic |
  505. | `apitap import <url-or-file>` | Import OpenAPI spec or skill file |
  506. | `apitap import --from apis-guru` | Bulk import from APIs.guru directory |
  507. | `apitap list` | List available skill files |
  508. | `apitap show <domain>` | Show endpoints for a domain |
  509. | `apitap search <query>` | Search skill files by domain or endpoint |
  510. | `apitap replay <domain> <id> [key=val...]` | Replay an API endpoint |
  511. | `apitap refresh <domain>` | Refresh auth tokens via browser |
  512. | `apitap auth [domain]` | View or manage stored auth |
  513. | `apitap auth request <domain>` | Open a browser for human login, store the session |
  514. | `apitap mcp` | Run the full ApiTap MCP server over stdio |
  515. | `apitap serve <domain>` | Serve a skill file as an MCP server |
  516. | `apitap inspect <url>` | Discover APIs without saving |
  517. | `apitap stats` | Show token savings report |
  518. | `apitap index [domain]` | View passive index from Chrome extension |
  519. | `apitap audit` | Audit stored skill files and credentials |
  520. | `apitap doctor` | Offline hygiene check for the skill store (junk domains, beacons, dupes, stale/unsigned files) |
  521. | `apitap forget <domain>` | Remove skill file and credentials for a domain |
  522. | `apitap --version` | Print version |
  523. ### Import flags
  524. | Flag | Description |
  525. |------|-------------|
  526. | `--from apis-guru` | Bulk import from APIs.guru directory |
  527. | `--search <query>` | Filter APIs.guru by provider or title |
  528. | `--limit <N>` | Max APIs to import (default: 100) |
  529. | `--no-auth-only` | Skip APIs requiring authentication |
  530. | `--dry-run` | Show what would be imported without writing |
  531. | `--update` | Skip APIs unchanged since last import |
  532. | `--force` | Always reimport regardless of history |
  533. ### Capture flags
  534. | Flag | Description |
  535. |------|-------------|
  536. | `--all-domains` | Capture traffic from all domains (default: target domain only) |
  537. | `--preview` | Include response data previews |
  538. | `--duration <sec>` | Stop capture after N seconds |
  539. | `--port <port>` | Connect to specific CDP port |
  540. | `--launch` | Always launch a new browser |
  541. | `--attach` | Only attach to existing browser |
  542. | `--no-scrub` | Disable PII scrubbing |
  543. | `--no-verify` | Skip auto-verification of GET endpoints |
  544. | `--domain <glob>` | Filter traffic by domain glob (attach mode, e.g. `*.github.com`) |
  545. ## Development
  546. ```bash
  547. git clone https://github.com/n1byn1kt/apitap.git
  548. cd apitap
  549. npm install
  550. npm test # ~1587 tests, Node built-in test runner
  551. npm run typecheck # Type checking
  552. npm run build # Compile to dist/
  553. npx tsx src/cli.ts capture <url> # Run from source
  554. ```
  555. ## Contact
  556. Questions, feedback, or issues? -> **[hello@apitap.io](mailto:hello@apitap.io)**
  557. ## License
  558. [Apache License 2.0](./LICENSE) — free and open source, no restrictions on use. ApiTap's BSL scheduled conversion to Apache 2.0 for 2029; we invoked the early-conversion clause on July 19, 2026 instead ([details](./RELICENSING.md)).
src/trapaware/signatures.ts · Bundled script · 111 lines · 3 findings marked
  1. // src/trapaware/signatures.ts
  2. /**
  3. * Tier 1 — Explicit role markers (high signal, near-zero false positive).
  4. * Line-prefix anchors (case-insensitive, whitespace-leading allowed).
  5. */
  6. export const TIER1_LINE_PREFIXES: readonly string[] = Object.freeze([
  7. 'system',
  8. 'user',
  9. 'assistant',
  10. 'ai',
  11. 'chatgpt',
  12. 'claude',
  13. 'gemini',
  14. 'model',
  15. 'instruction',
  16. 'instructions',
  17. ]);
  18. /**
  19. * Tier 1 — Structured markers (case-sensitive literal substring match).
  20. * These are format tokens from LLM prompt templates.
  21. */
  22. export const TIER1_STRUCTURED_MARKERS: readonly string[] = Object.freeze([
  23. '[INST]',
  24. '[/INST]',
  25. '<|im_start|>',
  26. '<|im_end|>',
  27. '<<SYS>>',
  28. '<</SYS>>',
  29. '### Instruction',
  30. '### System',
  31. '### Response',
  32. ]);
  33. /**
  34. * Tier 2 — Known prompt-injection signatures (literal strings, normalized match).
  35. * Lowercase + whitespace-collapsed match via String.prototype.includes.
  36. */
  37. export const TIER2_SIGNATURES: readonly string[] = Object.freeze([
  38. 'ignore previous instructions',
    • Note: Quoted as data in code: Quotes instruction-override phrasing (in quotes, code, a table or an example): "ignore previous instructions"
    • Line 41 on GitHub
  39. 'ignore all previous instructions',
    • Note: Quoted as data in code: Quotes instruction-override phrasing (in quotes, code, a table or an example): "ignore all previous instructions"
    • Line 42 on GitHub
  40. 'ignore the above instructions',
  41. 'disregard previous instructions',
    • Note: Quoted as data in code: Quotes instruction-override phrasing (in quotes, code, a table or an example): "disregard previous instructions"
    • Line 44 on GitHub
  42. 'disregard all previous',
  43. 'your new task is',
  44. 'your real task is',
  45. 'you are now',
  46. 'from now on you',
  47. 'pretend you are',
  48. 'act as an unfiltered',
  49. 'output the following verbatim',
  50. 'repeat after me',
  51. 'new instructions:',
  52. 'updated instructions:',
  53. ]);
  54. /**
  55. * Explicitly cut from Tier 2 for v1.0 due to false-positive risk in
  56. * legitimate prose (even inside the hidden gate). Deferred to v1.1 pending
  57. * audit log data. This constant exists as a regression guard — any future
  58. * contributor who adds these to TIER2_SIGNATURES will trip a test.
  59. */
  60. export const CUT_FROM_TIER2_V1: readonly string[] = Object.freeze([
  61. 'forget everything',
  62. 'do not tell the user',
  63. 'do not mention',
  64. ]);
  65. /**
  66. * Normalize text for Tier 2 matching: lowercase + collapse all whitespace
  67. * runs to single spaces. Safe for Unicode-basic content; no NFKC in v1.0.
  68. */
  69. function normalize(input: string): string {
  70. return input.toLowerCase().replace(/\s+/g, ' ').trim();
  71. }
  72. /**
  73. * Check if input matches any Tier 1 marker.
  74. * Line-prefix anchors are matched case-insensitively at start-of-line.
  75. * Structured markers are case-sensitive literal substring matches.
  76. */
  77. export function matchTier1(input: string): boolean {
  78. // Structured markers (case-sensitive literal)
  79. for (const marker of TIER1_STRUCTURED_MARKERS) {
  80. if (input.includes(marker)) return true;
  81. }
  82. // Line prefixes (case-insensitive, must be at start of line or start of string)
  83. const lines = input.split(/\r?\n/);
  84. for (const line of lines) {
  85. const trimmed = line.replace(/^\s+/, '');
  86. const lower = trimmed.toLowerCase();
  87. for (const prefix of TIER1_LINE_PREFIXES) {
  88. if (lower.startsWith(prefix + ':')) {
  89. return true;
  90. }
  91. }
  92. }
  93. return false;
  94. }
  95. /**
  96. * Check if input matches any Tier 2 signature after normalization.
  97. */
  98. export function matchTier2(input: string): boolean {
  99. const normalized = normalize(input);
  100. for (const sig of TIER2_SIGNATURES) {
  101. if (normalized.includes(sig)) return true;
  102. }
  103. return false;
  104. }

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.