---
description: Use Shaker Scan as a security gate for preview deploys, merge-sensitive changes, and release checks.
globs:
alwaysApply: false
---

# Shaker Scan Rule

Save this file as `.cursor/rules/shakerscan-gate.mdc`.

# ShakerScan Agent Gate

Use this skill when Shaker should become part of an automated workflow rather than a dashboard-only tool.

Hosted production base URL: `https://shakerscan.com`

If you run Shaker Scan in another environment, replace that base URL accordingly. Relative API paths below are shown so the same workflow also works for self-hosted or local deployments.

## What this skill does

- Connects an agent to Shaker through MCP or direct HTTP
- Uses the current live API surface:
  - `POST /api/v1/scan`
  - `GET /api/v1/scan`
  - `GET /api/v1/scans`
  - `GET /api/v1/findings`
  - `POST /api/v1/findings/:id/verify`
  - `POST /api/v1/policy/evaluate`
  - `GET /api/v1/evidence/:id`
  - `POST /api/v1/evidence/:id/token`
  - `POST /api/v1/approval-tokens/verify`
  - `POST /api/v1/findings/:id/remediate`
  - `GET /api/v1/remediation/:id`
  - `GET /api/v1/usage`
- Applies an evidence-backed workflow decision when verify and policy are available, with a fallback heuristic only when needed

## Quick selection

- For Claude Code or Cursor: use MCP first
- For CI or bots: use the CLI gate command first, then direct HTTP when you need raw control
- For Codex-style agents: use this skill for procedure and MCP, CLI, or HTTP for execution

## Copy-ready setup

### MCP for Claude Code or Cursor

```json
{
  "mcpServers": {
    "shakerscan": {
      "command": "npx",
      "args": ["-y", "shakerscan-mcp"],
      "env": {
        "SCANNER_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}
```

### CLI gate

```bash
npx -y shakerscan gate \
  --api-key "$SHAKER_API_KEY" \
  --target "$TARGET_URL" \
  --scan-type quick \
  --environment preview \
  --policy-pack preview-fast \
  --approval-token true \
  --approval-token-audience github-actions
```

### Minimal direct HTTP flow

Base URL: `https://shakerscan.com`

1. `POST https://shakerscan.com/api/v1/scan`
2. Poll `GET https://shakerscan.com/api/v1/scan?id=...`
3. `GET https://shakerscan.com/api/v1/findings?scan_id=...`
4. `POST https://shakerscan.com/api/v1/findings/:id/verify` for supported critical and high findings
5. `POST https://shakerscan.com/api/v1/policy/evaluate`
6. `GET https://shakerscan.com/api/v1/evidence/:id`
7. If allow, `POST https://shakerscan.com/api/v1/evidence/:id/token`
8. If blocked, optionally `POST https://shakerscan.com/api/v1/findings/:id/remediate`

## Inputs to ask for

- Target URL
- Environment: `preview`, `staging`, or `production`
- Policy pack: usually `preview-fast` or `release-strict`
- Whether the workflow needs an approval token audience such as `github-actions`
- Whether the user wants remediation when the result is `block` or `needs_approval`

## Default workflow

1. Confirm the target belongs to the user or they have permission.
2. Prefer a quick, non-invasive scan for preview or CI flows.
3. Submit the scan.
4. Poll until `completed` or `failed`.
5. Fetch findings.
6. Verify critical and high findings that support deterministic retesting.
7. Run policy evaluation for the scan, naming a `policy_pack` when the workflow needs an explicit gate mode such as `preview-fast`, `release-strict`, or a tenant custom pack.
8. Fetch evidence if the workflow needs a durable artifact.
9. Mint an approval token when the effective decision is `allow` and a downstream system needs signed proof.
10. Request remediation for blocked or high-risk findings when the workflow needs a durable fix plan, patch suggestion, or PR draft.
11. Fetch usage if the workflow needs reporting or budget awareness.
12. Return the policy decision when available. Fallback to a conservative decision only if verify or policy cannot run:

- `block` if any `critical` findings exist
- `needs_approval` if any `high` findings exist
- `allow` otherwise

State clearly whether the decision came from `evaluate_policy` or from the fallback heuristic.

## Operational rules

- Prefer `quick: true` and `public: true` unless the user explicitly wants deeper testing and the target is eligible.
- If the API returns a domain-verification or plan restriction error, downgrade to the safe scan path and explain why.
- Keep findings summaries compact. Show top critical and high issues first.
- If using MCP, ask the model to call the Shaker tools directly instead of reimplementing scan orchestration in text.
- When verification returns `unsupported`, preserve the finding in the decision path and call that out.

## Output shape

When acting as a gate, return:

- `decision`: `allow | block | needs_approval`
- `reason`: one sentence
- `scan_id`
- `critical_count`
- `high_count`
- `evidence_id`
- `next_step`