diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 83c7909..64f8739 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "arcjet", "version": "1.0.0", - "description": "Runtime security for your app — abuse protection, budget controls & rate limiting, prompt injection detection, and PII blocking. Connects your AI agent to the Arcjet MCP server and provides security-aware coding guidance.", + "description": "Runtime security for your app — abuse protection, budget controls & rate limiting, prompt injection detection, and PII blocking. Connects your AI agent to the Arcjet MCP server, invokes the Arcjet CLI for streaming and project-local skills, and provides security-aware coding guidance.", "author": { "name": "Arcjet", "email": "support@arcjet.com", diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 83c7909..64f8739 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "arcjet", "version": "1.0.0", - "description": "Runtime security for your app — abuse protection, budget controls & rate limiting, prompt injection detection, and PII blocking. Connects your AI agent to the Arcjet MCP server and provides security-aware coding guidance.", + "description": "Runtime security for your app — abuse protection, budget controls & rate limiting, prompt injection detection, and PII blocking. Connects your AI agent to the Arcjet MCP server, invokes the Arcjet CLI for streaming and project-local skills, and provides security-aware coding guidance.", "author": { "name": "Arcjet", "email": "support@arcjet.com", diff --git a/.plugin/plugin.json b/.plugin/plugin.json index 83c7909..64f8739 100644 --- a/.plugin/plugin.json +++ b/.plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "arcjet", "version": "1.0.0", - "description": "Runtime security for your app — abuse protection, budget controls & rate limiting, prompt injection detection, and PII blocking. Connects your AI agent to the Arcjet MCP server and provides security-aware coding guidance.", + "description": "Runtime security for your app — abuse protection, budget controls & rate limiting, prompt injection detection, and PII blocking. Connects your AI agent to the Arcjet MCP server, invokes the Arcjet CLI for streaming and project-local skills, and provides security-aware coding guidance.", "author": { "name": "Arcjet", "email": "support@arcjet.com", diff --git a/CHANGELOG.md b/CHANGELOG.md index 863d4c0..5dcbf2e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/). +## [Unreleased] + +### Added + +- Arcjet CLI integration. The plugin now invokes the CLI for capabilities + the MCP server does not expose: `arcjet watch` for live request streaming + during incident response, and `arcjet skills install` for project-local + skill installation. Commands run via `npx -y @arcjet/cli@latest` so no + install is required. Setup, read-side analysis, and rule CRUD continue to + use the MCP server. +- New `rules/arcjet-cli.mdc` rule explaining when to reach for the CLI vs + MCP, the npx invocation pattern, and agent-friendly flags + (`--output json`, `--fields`). + +### Changed + +- `agents/security-analyst.md` now uses `arcjet watch` for continuous + monitoring during active incidents, instead of polling `list-requests` + over MCP. +- `skills/protect-route`, `skills/add-ai-protection`, and + `skills/add-guard-protection` now end with an optional step that runs + `arcjet skills install` to write `ARCJET.md` into the project. + ## [1.0.0] - 2026-04-08 ### Added diff --git a/README.md b/README.md index 896e373..f741f2a 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ The [Arcjet plugin](https://github.com/arcjet/arcjet-plugin) turns any supported AI coding agent into a security expert. It pre-loads agents with knowledge of the Arcjet security platform and automatically injects the right guidance based on what you're working on — framework-specific SDK patterns, protection rules, and best practices. - **MCP integration** — connects to the [Arcjet MCP Server](https://docs.arcjet.com/mcp-server) for traffic analysis, request inspection, IP investigation, and remote rule management +- **CLI integration** — invokes the [Arcjet CLI](https://docs.arcjet.com/cli) for capabilities the MCP server does not expose (live request streaming, project-local skill installation) - **Security-aware coding rules** — framework-specific guidance activates automatically when you work in route handlers, API endpoints, and AI/LLM code - **Skills** — task-oriented workflows for adding protection to routes and securing AI endpoints - **Security analyst agent** — investigates threats, analyzes traffic, and manages rules via MCP @@ -35,13 +36,14 @@ After installing, guidance activates automatically. The plugin detects what you' Rules provide passive guidance that activates when you work in matching files: -| Rule | Activates on | Guidance | -| ------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------- | -| SDK patterns | `**/lib/arcjet*`, `**/arcjet*` | Single instance, `protect()` in handlers, `withRule()`, decision handling | -| Next.js | `app/**/route.ts`, `app/**/page.tsx`, `pages/api/**` | Correct imports, route handlers vs pages vs server components, no middleware | -| Express/Node | `**/server.ts`, `**/routes/**` | Correct adapter packages, no `app.use()` middleware, proxy config | -| Python | `**/*.py`, `pyproject.toml` | Snake_case API, enum values, async vs sync clients | -| AI apps | `**/chat/**`, `**/api/chat*`, `**/api/completion*` | Layered protection, token budgets, PII blocking, prompt injection | +| Rule | Activates on | Guidance | +| ------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------- | +| SDK patterns | `**/lib/arcjet*`, `**/arcjet*` | Single instance, `protect()` in handlers, `withRule()`, decision handling | +| Next.js | `app/**/route.ts`, `app/**/page.tsx`, `pages/api/**` | Correct imports, route handlers vs pages vs server components, no middleware | +| Express/Node | `**/server.ts`, `**/routes/**` | Correct adapter packages, no `app.use()` middleware, proxy config | +| Python | `**/*.py`, `pyproject.toml` | Snake_case API, enum values, async vs sync clients | +| AI apps | `**/chat/**`, `**/api/chat*`, `**/api/completion*` | Layered protection, token budgets, PII blocking, prompt injection | +| CLI | `**/lib/arcjet*`, `**/arcjet*`, `**/.env*` | When to use the CLI vs MCP, `npx -y @arcjet/cli@latest` invocation, agent flags | ### MCP Tools @@ -55,6 +57,17 @@ When connected, your agent can use the [Arcjet MCP server](https://docs.arcjet.c The MCP server connects automatically via OAuth when the plugin is installed. You can also connect it manually from `https://api.arcjet.com/mcp` +### CLI + +The plugin uses the [Arcjet CLI](https://docs.arcjet.com/cli) for two specific capabilities the MCP server does not expose: + +- **Live request streaming** — `arcjet watch --site-id ` is invoked by the security analyst agent during active incident response, when polling `list-requests` over MCP would be too coarse. +- **Project-local skill installation** — `arcjet skills install` is run after each skill workflow to write an `ARCJET.md` skills file into the project, giving future agent turns zero-round-trip discovery. + +No install is required. Commands are invoked as `npx -y @arcjet/cli@latest `, which works on macOS, Linux, and Windows. If a local `arcjet` binary is on `PATH` (Homebrew, npm global, release archive), the plugin uses it directly. CLI authentication uses the same browser-based device flow as `gh auth login` or `vercel login`. + +Setup commands, read-side analysis, and rule CRUD remain on the MCP server. + ### Security Analyst Agent The security analyst agent uses MCP tools for monitoring and incident response: diff --git a/agents/security-analyst.md b/agents/security-analyst.md index 867ab87..5a8f502 100644 --- a/agents/security-analyst.md +++ b/agents/security-analyst.md @@ -1,11 +1,14 @@ --- name: security-analyst -description: Arcjet security analyst — monitors traffic, investigates threats, manages remote rules, and provides security recommendations using the Arcjet MCP server. +description: Arcjet security analyst — monitors traffic, investigates threats, manages remote rules, and provides security recommendations using the Arcjet MCP server (with the Arcjet CLI for live request streaming). --- # Arcjet Security Analyst -You are a security analyst with access to the Arcjet MCP server. Your role is to help developers understand their application's security posture, investigate threats, and respond to attacks using Arcjet's tools. +You are a security analyst with access to the Arcjet MCP server and the +Arcjet CLI. Your role is to help developers understand their application's +security posture, investigate threats, and respond to attacks using Arcjet's +tools. ## Capabilities @@ -24,6 +27,17 @@ You have access to the Arcjet MCP server which provides these tools: - **`update-rule`** — update an existing rule - **`delete-rule`** — remove a rule +You also have access to the Arcjet CLI for capabilities the MCP server does +not expose. Prefer MCP for everything above — the CLI is for one specific +job: + +- **`arcjet watch --site-id `** — stream live requests as they arrive. + Use during active incident response or when verifying that a newly added + rule is matching the expected traffic. Invoke as + `npx -y @arcjet/cli@latest watch --site-id ` if no local `arcjet` + binary is on `PATH`. See `rules/arcjet-cli.mdc` for the full invocation + pattern. + ## When Invoked Perform a security review: @@ -69,7 +83,7 @@ When the user reports an active attack or suspicious activity: 2. **Identify** — find the attack pattern: common IP ranges, user agents, paths, or countries. 3. **Respond** — create a filter rule in `DRY_RUN` mode targeting the pattern. Verify it matches attack traffic without blocking legitimate users. 4. **Promote** — once verified, promote the rule to `LIVE` for immediate effect across all instances. -5. **Monitor** — continue watching with `list-requests` to confirm the attack is mitigated. +5. **Monitor** — for one-shot checks use `list-requests`. For continuous monitoring during an active incident, use the CLI: `arcjet watch --site-id ` (or `npx -y @arcjet/cli@latest watch --site-id ` if `arcjet` is not on `PATH`). Stream until the attack subsides, then return to the dashboard or `list-requests` for periodic checks. ## Remote Rules vs SDK Rules diff --git a/rules/arcjet-cli.mdc b/rules/arcjet-cli.mdc new file mode 100644 index 0000000..ec2a29c --- /dev/null +++ b/rules/arcjet-cli.mdc @@ -0,0 +1,70 @@ +--- +description: When to use the Arcjet CLI vs the MCP server, plus the zero-install npx invocation pattern and agent-friendly flags. +alwaysApply: false +globs: + - "**/lib/arcjet*" + - "**/arcjet*" + - "**/.env*" +--- + +## Arcjet CLI vs MCP + +The plugin connects to the Arcjet MCP server by default. Prefer MCP tool calls +for the read-side analysis hot path — `list-teams`, `list-sites`, +`get-site-key`, `list-requests`, `get-request-details`, `explain-decision`, +`analyze-traffic`, `get-anomalies`, `investigate-ip`, `get-dry-run-impact`, +`get-security-briefing`, and rule CRUD (`list-rules`, `create-rule`, +`update-rule`, `delete-rule`, `promote-rule`). MCP returns structured data and +renders confirmation prompts in the host UI. + +Reach for the Arcjet CLI in these specific cases: + +- **Live request streaming** — `arcjet watch --site-id ` polls the Arcjet + API and prints decisions as they happen. MCP has no streaming equivalent. + Use during active incident response or when verifying that a newly added + rule is matching the expected traffic. +- **Project-local skill installation** — `arcjet skills install` writes an + `ARCJET.md` skills file into the current project so future agent turns can + discover Arcjet capabilities without a docs round trip. The CLI is the + source of truth for skill content; do not duplicate it. +- **Guided SDK setup** — `arcjet skills initialize` runs an interactive setup + that installs the SDK and configures the application. Use as an alternative + to manually walking the user through `/arcjet:protect-route`. + +## Invocation + +The simplest invocation works on macOS, Linux, and Windows with no install +step: + +```bash +npx -y @arcjet/cli@latest +``` + +If a local `arcjet` binary is on `PATH` (Homebrew, npm global, release +archive), prefer it for lower latency. Detect with `command -v arcjet`. + +## Agent flags + +Always pass `--output json` so output is parseable. When stdout is not a TTY +JSON is the default, but be explicit. Pass `--fields ` to limit the +response to the keys you actually need — important for keeping the context +window small. + +```bash +arcjet requests list --site-id site_01abc123 --output json --fields id,conclusion,path +``` + +## Authentication + +Most users will not have `ARCJET_TOKEN` set. The CLI's default is the +browser-based device authorization flow: + +```bash +arcjet auth login +``` + +If the user has already authenticated with the CLI, subsequent commands work +without further prompts. In CI or non-interactive runs, set `ARCJET_TOKEN` +instead of running `auth login`. + +Ref: https://docs.arcjet.com/cli diff --git a/skills/add-ai-protection/SKILL.md b/skills/add-ai-protection/SKILL.md index 6361213..72ef083 100644 --- a/skills/add-ai-protection/SKILL.md +++ b/skills/add-ai-protection/SKILL.md @@ -157,6 +157,22 @@ If the user wants a full security review, suggest the `/arcjet:security-analyst` The Arcjet dashboard at https://app.arcjet.com is also available for visual inspection. +## Step 5: Install Project-Local Skills (Recommended) + +Run the Arcjet CLI to write an `ARCJET.md` skills file into the current project. Future agent turns can then discover Arcjet capabilities without fetching the docs. + +```bash +npx -y @arcjet/cli@latest skills install +``` + +Or, if `arcjet` is on `PATH`: + +```bash +arcjet skills install +``` + +The CLI uses the same authentication state as the MCP server. If the user has not yet authenticated, run `arcjet auth login` (browser-based device flow). See `rules/arcjet-cli.mdc` for guidance on when to use the CLI vs MCP. + ## Common Patterns **Streaming responses**: Call `protect()` before starting the stream. If denied, return the error before opening the stream — don't start streaming and then abort. diff --git a/skills/add-guard-protection/SKILL.md b/skills/add-guard-protection/SKILL.md index ae24e9d..9f984bb 100644 --- a/skills/add-guard-protection/SKILL.md +++ b/skills/add-guard-protection/SKILL.md @@ -143,6 +143,22 @@ If the user wants a full security review, suggest the `/arcjet:security-analyst` The Arcjet dashboard at https://app.arcjet.com is also available for visual inspection. +## Step 8: Install Project-Local Skills (Recommended) + +Run the Arcjet CLI to write an `ARCJET.md` skills file into the current project. Future agent turns can then discover Arcjet capabilities without fetching the docs. + +```bash +npx -y @arcjet/cli@latest skills install +``` + +Or, if `arcjet` is on `PATH`: + +```bash +arcjet skills install +``` + +The CLI uses the same authentication state as the MCP server. If the user has not yet authenticated, run `arcjet auth login` (browser-based device flow). See `rules/arcjet-cli.mdc` for guidance on when to use the CLI vs MCP. + ## Common Mistakes to Avoid - **Wrapping guard in a shared helper function** — calling `guard()` through a `guardToolCall()` or `protectCall()` wrapper hides which rules apply to each operation. Call `guard()` inline where each operation happens. diff --git a/skills/protect-route/SKILL.md b/skills/protect-route/SKILL.md index aec4997..8b47b0b 100644 --- a/skills/protect-route/SKILL.md +++ b/skills/protect-route/SKILL.md @@ -153,6 +153,22 @@ If the user wants a full security review, suggest the `/arcjet:security-analyst` The Arcjet dashboard at https://app.arcjet.com is also available for visual inspection. +## Step 6: Install Project-Local Skills (Recommended) + +Run the Arcjet CLI to write an `ARCJET.md` skills file into the current project. Future agent turns can then discover Arcjet capabilities without fetching the docs. + +```bash +npx -y @arcjet/cli@latest skills install +``` + +Or, if `arcjet` is on `PATH`: + +```bash +arcjet skills install +``` + +The CLI uses the same authentication state as the MCP server. If the user has not yet authenticated, run `arcjet auth login` (browser-based device flow). See `rules/arcjet-cli.mdc` for guidance on when to use the CLI vs MCP. + ## Common Mistakes to Avoid - Creating a new Arcjet instance per request (causes connection overhead)