Skip to content

SKILL.md

Latest commit

 

History

History
199 lines (151 loc) · 8.02 KB

SKILL.md

File metadata and controls

199 lines (151 loc) · 8.02 KB
Raw
name snir-web-intelligence
description Capture web screenshots and collect page intelligence with the snir CLI, HTTP API, Go SDK, and CDP provider. Use when you need browser-based screenshots, HTML/headers/cookies/network evidence, batch URL or host scanning, device emulation, proxy rotation, or SQLite/JSONL/CSV scan outputs.

snir Web Intelligence

Use snir as a Chrome DevTools Protocol based web screenshot and intelligence collector. It can capture single pages, batch URL lists, CIDR-expanded targets, and host/IP lists expanded across common web ports.

Start Here

Prefer the bundled install helper when available:

./scripts/install-snir.sh
snir version

Or install the latest prebuilt binary manually:

LATEST=$(curl -s https://api.github.com/repos/cyberspacesec/snir-skills/releases/latest | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1/')
OS=$(uname -s | sed 's/Linux/Linux/;s/Darwin/Darwin/;s/FreeBSD/Freebsd/;s/OpenBSD/Openbsd/;s/NetBSD/Netbsd/')
ARCH=$(uname -m | sed 's/x86_64/x86_64/;s/aarch64/arm64/;s/arm64/arm64/')
curl -L -o snir.tar.gz "https://github.com/cyberspacesec/snir-skills/releases/download/${LATEST}/snir-skills_${OS}_${ARCH}.tar.gz"
tar xzf snir.tar.gz snir
chmod +x snir
sudo mv snir /usr/local/bin/
snir version

If working from this repository (build from source):

# 1. Install Go 1.26+ from https://go.dev/dl/
# 2. Clone and build
git clone https://github.com/cyberspacesec/snir-skills.git
cd snir-skills
make build                     # builds ./snir with version/commit metadata
./snir version

# 3. (Optional) Install to a directory on PATH
make install                   # go install into $GOPATH/bin
# or manually:
sudo install -m 0755 snir /usr/local/bin/snir

# 4. (Optional) Build for a different platform (no Chrome needed on build host)
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o snir-arm64 .

make build injects version info via ldflags (see Makefile); make release-test runs goreleaser --snapshot to validate the full release pipeline locally without publishing.

Common Tasks

Single page screenshot:

snir scan example.com

Collect page evidence:

snir scan example.com --full-page --save-html --save-headers --save-cookies --save-console --save-network

Batch scan URLs from a file:

snir scan file -f urls.txt --threads 10 --write-jsonl --db

Expand bare hosts/IPs across common web ports:

snir scan file -f hosts.txt --ports 80,443,8080,8443 --write-jsonl --db

Run the HTTP API:

snir api --host 127.0.0.1 --port 8080 --api-key secret

Interact with a page (click, fill form, submit) — useful for login flows:

# Via HTTP API — POST /screenshot with actions array
curl -s -X POST http://127.0.0.1:8080/screenshot \
  -H "X-API-Key: secret" -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/login",
    "save_html": true,
    "save_cookies": true,
    "actions": [
      {"type": "type",  "selector": "#username", "value": "admin"},
      {"type": "type",  "selector": "#password", "value": "secret"},
      {"type": "click", "selector": "#login-btn", "wait_time": 2000}
    ]
  }'

# Or use the form helper (fills fields + submits in one step)
curl -s -X POST http://127.0.0.1:8080/screenshot \
  -H "X-API-Key: secret" -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/login",
    "form": {
      "fields": [
        {"selector": "#user", "value": "admin"},
        {"selector": "#pass", "value": "secret"}
      ],
      "submit_selector": "button[type=submit]",
      "wait_after_submit": 2000
    }
  }'

Query historical scan results stored in SQLite (requires --db-path at API startup):

# List recent results
curl -s "http://127.0.0.1:8080/results?limit=20" -H "X-API-Key: secret"

# Find all scans for a host
curl -s "http://127.0.0.1:8080/results/by-host?host=example.com" -H "X-API-Key: secret"

# Exact URL lookup
curl -s "http://127.0.0.1:8080/results/by-url?url=https://example.com" -H "X-API-Key: secret"

# Get one result by ID
curl -s "http://127.0.0.1:8080/results/42" -H "X-API-Key: secret"

Generate an HTML report from a JSONL scan output:

snir report html --input results.jsonl --output report.html

Merge multiple JSONL result files and convert to HTML:

snir report merge --files scan1.jsonl,scan2.jsonl --output merged.jsonl
snir report html --input merged.jsonl --output report.html

Start a shared Chrome provider for cross-process reuse (advanced):

# Start the provider; exposes Chrome's CDP WebSocket at :9222 and a query API at :9223
snir provider --port 9223 --chrome-port 9222 --max-concurrent 4

# Query the provider's WebSocket URL
curl http://127.0.0.1:9223/ws

# Use in another snir command
snir scan target.com --wss ws://127.0.0.1:9222/devtools/browser/...

# Use in Go SDK (auto-discover via provider query API)
# sdk.AutoConnectClient(sdk.DefaultClientOptions())

Inject JavaScript before or after page load:

# Run JS after load (evaluate and capture result)
snir scan example.com --js "document.title" --save-html

# Run JS before navigation (set up hooks)
snir scan example.com --js "window.__intercepted=[]" --run-js-before

Progressive Documentation

Open these files only when the task needs the extra detail:

  • references/README.md - skill bundle structure and when to open each resource.
  • references/scan-workflows.md - task-oriented CLI scan patterns.
  • references/api-and-sdk.md - HTTP API, Go SDK, and CDP provider integration notes.
  • references/outputs-and-evidence.md - result fields, persistence formats, and evidence collection.
  • scripts/install-snir.sh - portable install helper for Linux, macOS, FreeBSD, OpenBSD, and NetBSD.
  • evals/evals.json - realistic skill evaluation prompts and expectations.
  • docs/superpowers/SKILLS.md - full skill index, installation paths, command map, and flag overview.
  • docs/superpowers/scan.md - CLI screenshot, batch scan, ports, devices, proxies, evidence, and output options.
  • docs/superpowers/api.md - HTTP API server, auth, endpoints, request and response schema.
  • docs/superpowers/provider.md - shared Chrome/CDP provider for reuse across processes.
  • docs/superpowers/report.md - report generation and conversion workflows.
  • docs/superpowers/webserve.md - local web serving for generated outputs.
  • docs/skills.md - broader CLI, Go SDK, HTTP API, and provider reference.

Operating Notes

  • Screenshot capture requires Chrome or Chromium unless --wss points to a remote Chrome instance.
  • --ports expands URL candidates for web capture; it is not TCP/UDP port discovery.
  • Use --db --db-path <file> when downstream analysis needs structured endpoint metadata and captured evidence.
  • Use --write-jsonl for streaming or append-friendly pipelines.
  • Stay within authorized scope when scanning third-party assets.
  • Access control (SSRF defense): the default-deny allowlist blocks any target not listed. snir api --enable-allowlist --allowlist-pattern example.com permits only example.com and its subdomains, rejecting internal IPs, cloud metadata addresses, and any other host automatically. The blacklist (--enable-blacklist) is also enforced on every path — HTTP API, single-URL CLI, and SDK — not just batch scans. Combine both when the API is reachable from untrusted networks (e.g. --enable-allowlist --allowlist-pattern 10.0.0.0/8 --allowlist-pattern example.com).
  • SSRF hardening enforced regardless of flags: only http/https schemes are allowed, and any target whose host (including decimal/hex/octal integer IP variants such as 2130706433 or 0177.0.0.1, DNS-resolved records, and redirects) resolves to protected internal ranges (loopback, RFC1918, link-local, cloud metadata, IPv6 ULA) is rejected — even if the allowlist is off. After capture, the actual requested hosts are re-checked; a page that internally fetches an internal IP or escapes to a non-http scheme is flagged failed with an SSRF reason. This defeats DNS rebinding, in-page JS probing of the internal network, and redirect escapes.