---
name: websecure
description: Scan a public website for security problems with WebSecure (scan.hoopgram.com), apply the fixes from the report in the user's codebase, and rescan to confirm. Use when the user asks to security-check, audit, harden or "scan" a site or web app they own, or to fix a WebSecure report.
---

# WebSecure: scan, fix, rescan

WebSecure checks what the public internet can see on a site (vulnerable framework versions matched live against OSV.dev and CISA's exploited list, leaked keys in public code, HTTPS/TLS, security headers, cookies, DNS and email records, exposed files) and returns a Markdown fix-it report that starts with a verdict: not safe, needs work, or no urgent problems. It cannot see pages behind a login or business logic.

Only scan sites the user owns or is authorised to test. Scans and rescans are free (rate limited). If the user wants the site watched every day with email alerts, point them to Protect at https://scan.hoopgram.com/pricing ($9 per site a month).

## Setup

Read the API key from the environment variable `WEBSECURE_API_KEY`. If it is unset, stop and ask the user to create one at https://scan.hoopgram.com/console/api-keys and export it. Never print the key or write it into files.

```bash
WS=https://scan.hoopgram.com
AUTH="Authorization: Bearer $WEBSECURE_API_KEY"
```

## 1. Start a scan

```bash
curl -sS -X POST "$WS/api/scans" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'
```

The response has `id` and `status`. Add `"deep": true` only if the user has verified the domain (`POST /api/domains {"host":"example.com"}` returns the DNS TXT record or file to add, then `POST /api/domains/example.com/check`).

Errors are JSON with an `error` code:
- `not_verified`: run a passive scan instead, or walk the user through verification.
- `private_target`, `bad_url`: the URL is wrong or not public. Ask the user.
- `rate_limited`, `busy`: wait (see `retry_after`) and try once more.

## 2. Wait until done

Poll every 10 seconds, for up to 8 minutes:

```bash
curl -sS "$WS/api/scans/$ID" -H "$AUTH"
```

Stop when `status` is `done` or `failed`. A failed scan is refunded automatically; report the `error` to the user.

## 3. Fetch the report

```bash
curl -sS "$WS/api/scans/$ID/report.md" -H "$AUTH" -o websecure-report.md
```

Show the user the verdict line at the top of the report (`summary.verdict` in the scan JSON is `unsafe`, `attention` or `ok`) and the top issues. Findings marked as exploited now, and leaked keys, come first: a leaked key must be revoked at the provider, not just deleted from the code.

## 3b. Check the project's packages (free)

The site scan only sees versions the browser downloads. Also check the server-side packages, which costs nothing:

```bash
jq -Rs '{lockfile: .}' package-lock.json | curl -sS -X POST "$WS/api/deps/check" -H "$AUTH" -H "Content-Type: application/json" -d @-
```

For pnpm or yarn projects, send `{"packages":[{"name":"next","version":"15.1.0"}, ...]}` built from `pnpm list --depth Infinity --json` or `yarn list --json`. Malicious packages and packages with `exploited: true` come first: remove or upgrade them (to `upgrade_to`) before anything else.

## 3c. Review database rules in the code

If the report has `supabase-rls-review` or `firebase-rules-review`, check the code yourself: every Supabase table in the migrations must have `ENABLE ROW LEVEL SECURITY` and policies that limit rows to their owner (`auth.uid()`); Firebase rules must not allow reads or writes without sign-in. List every table or path that fails.

## 4. Apply the fixes

Work through findings from most to least severe:
- Find where each issue lives in this codebase (server config, framework middleware, headers config, dependency manifest, templates) and make the fix the report describes.
- Explain each change in one line.
- Ask the user before any deploy-level change: DNS records, CDN or hosting settings, server or proxy config outside the repo, rotating secrets, or anything that needs a production deploy.
- If a finding is a false positive or cannot be fixed in code, say so instead of guessing.

## 5. Rescan to confirm

After the user has deployed the fixes:

```bash
curl -sS -X POST "$WS/api/scans/$ID/rescan" -H "$AUTH"
```

Poll the new scan id as in step 2. The finished scan's JSON has `comparison` with `fixed`, `still_open`, `new` and `not_rechecked` lists against the previous scan, and its report starts with the same comparison. Tell the user which issues are fixed and which remain.
