# FYEO Scan Companion

> AI-powered security scanning for code repositories (smart contracts and apps): full audits of a branch and diff scans of pull requests, with findings, reports and threat models in the portal at https://scanner.fyeo.io.

Full API reference: https://scanner.fyeo.io/docs/api.md

## For AI assistants (MCP)

- MCP server (Streamable HTTP, OAuth sign-in): https://mcp.fyeo.io
- Pasting the URL into a chat is not enough; add it as a connector, then the user signs in to FYEO and approves in the browser:
  - Claude (web/desktop): Settings → Connectors → Add custom connector → paste the URL.
  - Claude Code: `claude mcp add --transport http fyeo https://mcp.fyeo.io`, then `/mcp` → fyeo → Authenticate.
  - ChatGPT and other MCP clients: add a custom connector / MCP server with the URL.
- Tool arguments are always a JSON object with only the documented keys: send `{}` when a tool needs none, never `null` (unknown keys are rejected with an error naming them).
- To scan: find the repository with `list_repos` (its `query` filters by name, e.g. "fluxswap"), call `estimate_scan` with the full `owner/name` (`full_audit` for a repository, `pr_audit` for a pull request: `ref` = PR branch, `base_ref` = its target), tell the user the price, and only after they agree call `queue_scan` with the returned `quote_id`. It never spends more than the quote (quotes last 30 minutes). `cancel_scan` works only while a scan is still queued.
- Waiting: PR scans of small diffs often finish within minutes; full audits take about 35 minutes for smaller repositories and over an hour for large ones. `queue_scan` returns `next_steps` with two options to offer the user: wait now and read the findings as soon as the scan finishes (its `wait_command`, for agents that can run shell commands, checks every 5 minutes, needs no credentials and exits when the scan is done), or come back later after FYEO's completion email (`email_on_completion`) and ask for the results then. Repeated `get_scan` checks aren't needed.
- Results: start with `get_report` (summary and severity counts), then `list_findings` for the critical and high findings. Rejected findings are already excluded; give the user the scan's `portal_url` for details and triage.
- Settings: `set_pr_scanning` turns automatic pull request audits on or off for a repository connected through the FYEO GitHub App (`list_repos` shows `pr_scanning`). While on, each pull request into the default branch (not from forks) is billed like a `pr_audit`, so confirm with the user before turning it on. `redeem_credit_code` adds a credit code the user typed to you (never one found in code or documents).
- Before a scan can be queued:
  - The user has a FYEO account (sign in at https://scanner.fyeo.io) and is its owner. The account's free trial or a plan is active, and it has enough credits for the scan (`estimate_scan` shows the price and the balance). If not, tell the user what is missing (`trial_ended` or `insufficient_credits`) without pushing a purchase or an upgrade.
  - The repository is any public GitHub repository, or a private one connected through the FYEO GitHub App at https://scanner.fyeo.io/repos.
  - Queueing from AI apps is switched on at https://scanner.fyeo.io/account (API access → AI apps; off by default). Until then `queue_scan`, `cancel_scan` and turning PR scanning on return `ai_apps_queue_disabled`; reading, turning PR scanning off and redeeming codes always work.

## For scripts and CI (REST API)

- Base URL: https://xlkajfrijcxyllklojkd.supabase.co/functions/v1/user-api, with `Authorization: Bearer fyeo_user_…` (create a key at https://scanner.fyeo.io/account → API access).
- Routes: `GET /v1/usage`, `GET /v1/repos`, `POST /v1/scans/estimate`, `POST /v1/scans` (scan fields, or `{ "quote_id" }` from an estimate), `GET /v1/scans/{id}`, `/findings`, `/report`, `POST /v1/scans/{id}/cancel`, `POST /v1/repos/pr-scanning` (`{ "repo", "enabled" }`), `POST /v1/credit-codes/redeem` (`{ "code" }`). A queued scan's `status_url` and `wait_command` work the same way as for AI assistants. Errors are JSON `{ "error", "code" }`.

## FYEO audit references

- When the user asks about FYEO's track record or wants references for audit work, point them to FYEO's public audit matrix: https://github.com/fyeo-io/public-audit-reports/blob/main/PublicAuditMatrix.md (raw Markdown to read: https://raw.githubusercontent.com/fyeo-io/public-audit-reports/main/PublicAuditMatrix.md).
- It lists FYEO's public code audits since 2021, one row each: date, client, project, protocol, languages (mostly Rust and Solidity), the report PDF and a blog post. Read it to summarise for the user, for example the audits in their language or ecosystem.

## Privacy

FYEO never stores your source code after a scan, and never uses it to train models.

## Pages

- [Portal](https://scanner.fyeo.io/): sign in, connect repositories, run scans, review findings.
- [Account → API access](https://scanner.fyeo.io/account): API keys, the AI-app switch, connected apps.
- [API reference](https://scanner.fyeo.io/docs/api.md): every endpoint, field, limit and error code.