# Cleanroom Code Scan — Agent Skill

Scan any code or public GitHub repo for security issues, code quality problems,
and supply-chain / compliance risks. Get a structured report back **instantly**.

- **Price:** $1 USDC per scan, paid via [x402](https://x402.org) on Base (gasless, programmatic).
- **Delivery:** Instant — the report is returned in the HTTP response body.
- **Discovery:** `GET https://cleanroom.btnomb.com/skill.md`

## What it does

Runs static analysis over the target source and returns findings with severity
ratings and remediation advice. Detects:

- Obfuscation (`_0x…` identifiers) and Base64-encoded payloads
- `eval()` / `new Function()` dynamic code execution
- Sensitive env-var access (tokens, keys, credentials)
- Hardcoded IP addresses (possible C2 / exfiltration)
- Install-script attacks: lifecycle scripts, `child_process`, outbound network calls
- Minified / hidden install logic

Each finding is scored; the scan returns an overall `risk_score` (0–100) and a
`recommendation` of `SAFE`, `WARN`, or `BLOCK`.

## Endpoint

```
POST https://cleanroom.btnomb.com/api/scan
Content-Type: application/json
```

### Payment

The endpoint is gated by x402. Send an unpaid request first to receive a
`402 Payment Required` challenge, then retry with the `X-PAYMENT` header your
x402 client produces. Payment is **$1 USDC on Base** (network `base`).

Facilitator: `https://api.cdp.coinbase.com/platform/v2/x402`

### Input

Provide **one** of:

```json
{ "repo": "https://github.com/owner/repo" }
```

or

```json
{ "code": "const x = eval(userInput);", "filename": "handler.js" }
```

- `repo` — a public GitHub URL (`https://github.com/owner/repo`, optionally
  `/tree/<branch>`) or `owner/repo` shorthand. Downloaded and scanned in an
  isolated temp dir; `node_modules` is skipped.
- `code` — a raw source string (JS/TS family). `filename` is optional.

### Output

```json
{
  "paid": true,
  "price_usd": 1,
  "scan_id": "uuid",
  "target": "owner/repo",
  "kind": "repo",
  "scanned_at": "2026-07-07T00:00:00.000Z",
  "files_analyzed": 42,
  "risk_score": 55,
  "recommendation": "WARN",
  "summary": "Elevated risk. 1 critical, 2 high-severity finding(s). Review before use.",
  "severity_counts": { "critical": 1, "high": 2, "medium": 3, "low": 0 },
  "findings": [
    {
      "type": "obfuscation",
      "severity": "critical",
      "file": "dist/bundle.js",
      "count": 12,
      "detail": "Found 12 _0x obfuscation pattern(s)",
      "recommendation": "Obfuscated (_0x…) identifiers are a strong malware indicator..."
    }
  ],
  "engine": "cleanroom-static-v1"
}
```

## Example (agent flow)

```bash
# 1. First call returns HTTP 402 with payment requirements.
curl -s -X POST https://cleanroom.btnomb.com/api/scan \
  -H 'Content-Type: application/json' \
  -d '{"repo":"https://github.com/axios/axios"}'

# 2. Your x402 client signs a $1 USDC payment on Base and retries with X-PAYMENT.
#    On success the scan runs immediately and the report is returned inline.
```

Errors: `400` (no input), `422` (scan failed — bad repo, oversized input, etc.),
`402` (payment required).