# SkillGuard
SkillGuard scans a SKILL.md URL or raw Markdown and returns a signed security report for agents.

It is meant to be used as a preflight gate before an agent or marketplace trusts a new skill.

Base URL:
https://skillguard-production.up.railway.app

Endpoints:

GET https://skillguard-production.up.railway.app/health
Checks that the service is online.

Example curl:
curl https://skillguard-production.up.railway.app/health

Example response:
{"service":"SkillGuard","version":"0.1.0","status":"ok","time":"2026-07-08T12:00:00Z"}

POST https://skillguard-production.up.railway.app/v1/scan
Scans a SKILL.md source. Use source_type "url" with source_url, or source_type "content" with content.

Example curl:
curl -X POST https://skillguard-production.up.railway.app/v1/scan \
  -H "Content-Type: application/json" \
  -d '{"source_type":"content","content":"# Demo\nBase URL: https://example.com\nGET https://example.com/health\nExample curl: curl https://example.com/health\nExample response: {\"status\":\"ok\"}"}'

Example response:
{"scan_id":"scan_example","status":"completed","verdict":"safe","score":100,"summary":"Verdict safe with score 100; 1 endpoint(s) extracted; 0 finding(s), 0 high-or-critical.","endpoints":[{"method":"GET","url":"https://example.com/health","path":"/health"}],"endpoint_probes":[{"method":"GET","url":"https://example.com/health","status":"passed","http_status":200,"elapsed_ms":42.1,"detail":"HTTP 200"}],"pipeline":[{"name":"fetch_source","status":"passed","detail":"source content loaded successfully"},{"name":"static_skill_review","status":"passed","detail":"0 static finding(s) detected"},{"name":"live_endpoint_probe","status":"passed","detail":"1 endpoint probe(s), 0 finding(s)"},{"name":"final_verdict","status":"passed","detail":"verdict=safe, score=100"}],"findings":[],"receipt":{"scan_id":"scan_example","content_sha256":"...","canonical_sha256":"...","verdict":"safe","signature":"...","signature_alg":"blake2b-keyed-v1"}}

GET https://skillguard-production.up.railway.app/v1/scans/{scan_id}
Fetches a previous scan report by scan_id.

Example curl:
curl https://skillguard-production.up.railway.app/v1/scans/scan_example

Example response:
{"scan_id":"scan_example","status":"completed","verdict":"safe","score":100}

POST https://skillguard-production.up.railway.app/v1/verify
Verifies a receipt returned by /v1/scan.

Example curl:
curl -X POST https://skillguard-production.up.railway.app/v1/verify -H "Content-Type: application/json" -d '{"receipt":{"scan_id":"scan_example","issued_at":"2026-07-08T12:00:00Z","content_sha256":"...","canonical_sha256":"...","verdict":"safe","signature":"...","signature_alg":"blake2b-keyed-v1"}}'

Example response:
{"valid":true,"scan_id":"scan_example","reason":"verified"}

How an agent should use this:
1. Before using a new service skill, send its SKILL.md URL or text to POST /v1/scan.
2. Read verdict, score, findings, and recommendations.
3. If verdict is safe, use the extracted endpoints normally.
4. If verdict is needs_review, ask the user before using the skill.
5. If verdict is block, do not call the scanned service.
6. Keep the receipt if you need evidence of what was scanned and what verdict was returned.