How Talon Audit works

01 Running an audit

Enter a URL you own or are explicitly authorised to test into the console on the home page. Your first scan can run without an account; when you sign in, that scan is attached to your account and you get a workspace at /app — an Overview with what changed since your last visit, a cross-project Findings table, the verification queue, projects, monitoring, history, and Prospect (vendor due-diligence, run against sites you don't own). A headless Chromium instance at the edge renders the live page (JavaScript included), captures a full screenshot, and streams each instrument's progress to you in real time. A typical audit finishes in well under a minute. Entering a URL is not authorisation for active testing — Talon only performs passive, low-impact analysis (see §10).

Your first analysis is free. Free accounts get 4 audit page-runs/month; Studio (€79/month) and Desk (€179/month) lift that to 60 and 200. See pricing for full quota details.

02 Four analysis domains

Every finding is classified into exactly one domain.

• Exposure · externally observable security & privacy weaknesses: security headers, TLS & transport, third-party scripts, cookies & storage, mixed content.
• Integrity · whether the site works correctly: broken links, failed resources, unexpected HTTP responses.
• Experience · usability and performance: accessibility, rendered lab Core Web Vitals (LCP/CLS/FCP/TTFB, measured in one synthetic browser session), visual coherence.
• Conversion · whether visitors understand the offer and can act: value proposition, trust signals, CTA clarity, SEO.

03 Security instruments

Six passive Exposure instruments run on every audit today:

• Security headers · Content-Security-Policy (parsed for unsafe-inline, unsafe-eval, wildcard sources and missing object-src / base-uri / frame-ancestors), HSTS, X-Content-Type-Options, Referrer-Policy and clickjacking protection — recording the exact observed value and which response supplied it.
• TLS & transport · HTTP→HTTPS upgrade, HSTS lifetime and directives (includeSubDomains, preload), mixed content, and forms posting to insecure destinations. The served certificate’s issuer, protocol and expiry are observed from the live browser session, with expiry findings at 30/14/7 days. Certificate-chain completeness and cipher-suite coverage are not inspected and are reported as not observed.
• Third-party inventory · every external script, iframe, font and embedded service, classified as expected, privacy-relevant, security-relevant or requires review, with a flag for scripts loaded without Subresource Integrity.
• Cookies & browser storage · cookie flags (HttpOnly, Secure, SameSite) and storage key names captured during the render. Cookie and storage values are never stored; cookie names are shown so you can identify the affected cookie, and a session-style name is never asserted to be an authentication cookie.
• Secret detection · pattern-matches the rendered page source (inline scripts included) for well-known live-credential formats — AWS, Stripe, GitHub, Slack, Google API keys and private-key blocks. Conservative by design: only high-precision vendor key formats, redacted before display, never a generic "looks like a secret" heuristic. Runs only for a verified domain owner — never for a guest or an unverified account, since a false claim about a domain you don't control would be a serious credibility problem.
• Regression detection · each re-audit is compared to the previous audit of the same domain by stable fingerprint (New / Resolved deltas).

04 Finding taxonomy

Every finding has a single classification (Exposure / Integrity / Experience / Conversion) and a type (Verified exposure, Technical failure, Operational risk, User friction, Improvement opportunity, Requires review). Severity is one of Critical, High, Medium, Low, Informational. Each finding also carries a stable fingerprint, an affected resource, a status and, across audits, a change status (New / Resolved / Regressed / Unchanged).

05 Evidence, provenance & confidence

Every finding shows the exact evidence it was derived from, plus a provenance label and a confidence level, so AI inference is never presented with the authority of deterministic evidence:

• Verified — deterministic test · e.g. a header that is present or absent in the response.
• Observed — rendered browser or network evidence · e.g. a cookie or resource seen during the render.
• Inferred — AI-assisted analysis · e.g. a messaging or design critique. Shown with lower confidence.
• Advisory — best-practice recommendation.

06 Talon Score

Scoring is fully published. Severity weights: critical = 16, high = 9, medium = 4, low = 1.5, informational = 0.3, each multiplied by a provenance factor (Verified 1.0, Observed 0.85, Inferred 0.5, Advisory 0.15). Each domain's weighted penalty (P) maps to a 0–100 domain health via a saturating curve, health = 100 − 100 × P / (P + 25). The Talon Score is the weighted average of the four domain healths (Exposure 0.35, Integrity 0.30, Experience 0.25, Conversion 0.10). Interpretive (AI-inferred and advisory) findings can lower the score by at most 15 points below what the deterministic evidence alone produces. Grades: A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 60, F below 60. A score is never proof that a site is secure. Reports created under the previous single-score model are marked Legacy scoring model and are never silently reinterpreted.

07 Remediation prompts

Every finding ships with a remediation instruction written as a self-contained prompt for an AI coding tool such as Claude Code, Cursor or Copilot: it names the issue, the evidence and the required change. Generated prompts never contain secrets, cookies, tokens or private report URLs.

08 Verification & signed attestations

Talon does not scan your code. It signs what is live. Every completed audit, and every "Verify fix" re-check, can issue a portable, Ed25519-signed attestation — a small, canonical JSON document stating what Talon observed at a specific live URL, at a specific time, against a named and versioned check set. It's independently verifiable without a Talon account or API key: fetch the envelope from /api/attestation/<id>, fetch the public key from /.well-known/talon-attestation-key.json, and verify the Ed25519 signature yourself. The public /verify/<id> page does exactly this and shows its own verification snippet.

Every scan also carries a ship verdict: SHIP BLOCKED, SHIP OK, WITH ADVISORIES, or SHIP OK. A finding only blocks the ship if it is Critical or High severity and carries Verified or Observed provenance — an AI-inferred or advisory finding, even at Critical severity, can never block. This is deliberate: an unverified opinion should never be able to stop a release.

On a saved report, "Verify fix" re-runs the instrument behind a deterministic finding, or re-observes a supported browser-session finding (cookies, Web Vitals, certificate evidence), against the live URL — never against a cached page — and reports Verified resolved or Still present, each issuing its own attestation chained to the prior one's evidence digest. AI-inferred and unsupported findings need a full re-audit; an inferred finding that no longer appears is reported as an improvement, not a verified fix. Findings on saved reports carry a workflow status: Open, Acknowledged, In progress, Ready to verify, Resolved, Regressed, Accepted risk, or False positive.

09 Private reports & data handling

Audits are private by default. There is no public registry, feed or archive of analysed sites, and no endpoint that lists or enumerates scans, exposes aggregate scan activity, or searches across other customers' reports. Account-owned reports require the owning signed-in session or API key; a guest report opens only in the browser that ran it (an HttpOnly talon_guest cookie) — the report id alone is never a credential. Share a report through a revocable client share link. Sensitive values are redacted before storage. The demo report on the home page is entirely fictional (northstar-demo.example) and is never generated from customer data. Full details: Data handling & security.

There is deliberately no public listing, similarity-search or aggregate-stats endpoint. Our crawler identifies as TalonBot/1.0 (+https://talonaudit.com).

10 Passive-analysis limits

Talon reads what a site already exposes to any visitor. It does not exploit vulnerabilities, brute-force paths or credentials, run destructive tests, attempt authentication bypasses, or perform denial-of-service or unauthorised active scanning. Outbound requests are constrained by SSRF protections (private, loopback, link-local and metadata addresses are blocked and every redirect is re-validated), strict timeouts and redirect limits. A failed instrument is reported honestly and never counted as a pass.

11 Domain verification & planned checks

Basic passive checks run against public pages without verification. Domain verification itself is live in beta: add a domain in your account panel and prove ownership with a DNS TXT record, a hosted verification file, or a meta tag (verification expires after 180 days). Client-side secret detection (§03) is the first deeper, verified-domain-only check shipped. Still planned, clearly labelled wherever they appear: DNS & email-security posture, a conservative exposed-file scanner, technology and vulnerable-component inventory, and attack-surface / subdomain monitoring. They are not presented as shipped until they are.

12 Agency artifacts

Studio and Desk turn a scan into a client-billable deliverable. The white-label PDF (GET /api/pdf/<id>) has three parts: Part A carries every Verified/Observed finding — deterministic only, the part an agency stands behind; Part B is a clearly-headed advisory appendix for Inferred/Advisory findings, marked as AI-assisted opinion, never verified observation; Part C is a table of every attestation issued for that asset — published ones with their public verify URL, unpublished ones named as private records (publish one to make it verifiable by your client). A disclaimer footer — passive external observation, not a penetration test, not a certification of security — prints on every page and cannot be removed by branding. Configure your logo, colours, agency name and sender name in the workspace's Clients tab; Desk adds a custom cover-sheet intro and per-client branding overrides.

The client share portal (POST /api/assets/<id>/share mints a token; the raw token is shown once) publishes a read-only, always-current status page at /s/<token> — verdict, open findings, attestation history, last/next monitoring check, score trend. Studio shows light Talon chrome alongside your agency's name; Desk removes it entirely above the mandatory disclaimer. Revoke a share any time from the Clients tab; the link stops working immediately.

Monitoring & alerts. Monitored assets are re-scanned weekly (daily on Desk). Alerts go out only when something meaningful changes — and immediately when a site's verdict flips to SHIP BLOCKED, naming the blocking findings. Alerts go to the account email and, optionally, to a webhook you set in the workspace's Monitoring tab: any public https:// endpoint, including Slack and Discord incoming webhooks (the JSON body carries text for Slack, content for Discord, and a structured talon object for everything else).

The Talon Seal. For a monitored asset whose domain ownership you have verified (§11), you can publish a live badge from the Monitoring tab: /badge/domain/<domain>.svg shows the latest score and how recently it was verified, and links to /verify/domain/<domain>, which always redirects to the newest published attestation. A result that discloses a live weakness is never auto-published; if monitoring stops or falls behind, the badge reads STALE rather than showing an old result.

13 HTTP API & agents

Talon is agent-callable over plain HTTP — no SDK required. Authenticate with the talon_session cookie (browser), a Bearer API key (Authorization: Bearer talon_sk_…, see your account panel), or, for /api/audit only, one free unauthenticated guest scan. Every response is JSON.

• POST /api/audit · {"url": "https://example.com"} → Talon Score, domain scores, ship verdict, structured findings. Session, API key, or one free guest scan (same quota as the console).
• GET /api/report/<id> · one stored report — ownership-checked for account-owned scans; a guest report opens only from the browser that ran it. Non-owners get 404 (§09).
• GET /api/shot/<id>.png · that report's rendered screenshot.
• GET /api/pdf/<id> · the white-label PDF for that report (§12), same ownership gate.
• GET /api/attestation/<id> · a signed attestation envelope — public once published, capability-id-only otherwise.
• POST /api/prospect · {"target": "vendor.com"} → a Prospect report for a site you don't own (session/API key, quota-gated).

POST /mcp speaks Model Context Protocol over streamable HTTP (JSON-RPC 2.0), authenticated the same way with a Bearer API key. Exactly four tools — talon_audit, talon_report, talon_verify_finding, talon_attestation — call tools/list for schemas. Crawl and report comparison stay in the HTTP API and the workspace, not on the MCP surface. Calls are synchronous and can take ~1–2 minutes; set client timeouts accordingly.

A machine-readable description is published at /openapi.json (OpenAPI 3.1, CORS-open). As in §09, there is deliberately no endpoint that lists or enumerates scans, exposes aggregate account activity, or searches across other users' reports.

14 CI: GitHub Action & CLI

Two free, MIT-licensed surfaces run the same audit outside the browser. Both call POST /api/audit and report the same ship verdict.

GitHub Action — raptorlabs/talon-verify-action. Scans a deployed URL, writes a job summary, and keeps a single PR comment current (edited in place, never a second comment). It fails the build only on blocking findings: critical or high severity that Talon observed deterministically. Advisory and AI-inferred findings are reported but never break a build, and a finding you have marked accepted-risk or false-positive in the workspace stays out of the gate.

- uses: raptorlabs/talon-verify-action@v1
  with:
    api-key: ${{ secrets.TALON_API_KEY }}
    url: https://app.example.com
    fail-on: high        # critical | high | none
    baseline: true       # fail only on findings new since the last scan

baseline: true is the setting that makes a gate survive contact with a real team: only findings new or regressed since the previous scan of that asset can fail the build, so a two-year-old missing header stops failing pull requests that had nothing to do with it. The first run has nothing to compare against, so it records the baseline and fails nothing, and says so in its summary. Outputs: verdict, attestation-id, verify-url, blocking-count, failing-count, score, grade, report-id.

CLI — @talon/cli. One command, no install, no account needed for your first scan.

npx @talon/cli scan https://app.example.com

Prints the verdict, the blocking findings and the attestation URL. Exit 0 for SHIP OK and SHIP OK WITH ADVISORIES, 1 for SHIP BLOCKED, and 2 when the scan could not be run at all — a quota refusal or a network failure is never reported as a clean bill of health. --json gives machine output; --key (or TALON_API_KEY) runs it against your account so the report is saved and becomes the baseline for the next scan.

Once published, anyone you send an attestation to can verify its Ed25519 signature against the published key set without a Talon account. A keyless (guest) scan's attestation is visible only in the browser that ran it until you save the report to an account. An account scan's attestation starts private, and one recording a live unresolved weakness needs your explicit confirmation before it can be published (§08).