How to use Assay

Scan, triage, and prove it.

Sign in through your identity provider, import a repository, run a scan, triage what it finds, and export an audit-grade report you can hand to a SOC 2 or ISO 27001 auditor.

Web console + /v1 API Evidence for SOC 2 CC4.1 / CC7.x ISO 27001 A.8.8 / A.8.29

Assay has two surfaces. The web console is what most people use — repositories, scans, findings, reports, compliance, audit, and admin. The HTTP API (everything under /v1) is what the console is built on; a few capabilities are API-only today and are marked API only below.

01Signing in

Assay holds no passwords. You log in through your organization's identity provider (OIDC — Keycloak, Auth0, Okta, Google, …), configured by an admin first.

Open the site. If you are not signed in, you get the Sign in screen.
Enter your organization login handle (usually the org slug) and click Continue to your identity provider.
Authenticate with your IdP. You are redirected back and land on your organization's Overview.

Your session is a secure, HttpOnly cookie — never readable by scripts, and it requires HTTPS. Log out ends the session server-side.

First run

On a brand-new deployment an admin must configure the OIDC provider for the org and create the first organization from the CLI (assay found-org). See the deployment guide.

02The console at a glance

Everything happens inside an organization, at /o/<your-org>/…. The left nav groups the screens, and a link is hidden if your seat lacks permission for it.

Evidence — Overview, Repositories
Record — Audit log, Compliance
Organization — Teams, Usage, Single sign-on, Settings, Legal

The Overview shows the org and a table of its repositories. The landing page (before you pick an org) lists the organizations your session can act in.

03Import a repository

Repositories are added one at a time by clone URL — there is no GitHub/GitLab "connect & pick" flow yet.

Go to Repositories → Import a repository.
Provide the full name (owner/name), an https:// clone URL without embedded credentials, and a fully-qualified default ref (e.g. refs/heads/main).
Submit. The repository is registered and an initial indexing job starts in the background.

Requires the repo.import permission (member seat and up).

04Run a scan

A scan indexes the code and produces findings you can review.

Open the repository → Repository detail.
Click Scan the default ref.
Watch it run — the scan streams live progress, and the scans table shows Scan, Ref, Commit, State, Gate, Started, and per-row Watch / Stop watching.

Scans are idempotent: if an equivalent scan is already running you are attached to it, not duplicated. You can cancel a running scan from its row. Requires scan.trigger; reading results needs scan.read.

05Review & triage findings

Findings are per-repository. Open Findings from a repository to review them.

critical high medium low info

The list is filterable and cursor-paged, and a repo that was never scanned reads differently from one that scanned clean. A finding's detail shows its severity, reachability (reachable / unknown), lifecycle status, CVE, affected package, an EPSS score, a KEV flag, the evidence trail, and a verifiable receipt.

Triage from the finding's panel with one of three dispositions — accept, reject, or needs info — plus a required note. There is no "false positive" suppression control, and a refuted finding is read-only. Requires finding.triage.

Principle

A machine never closes a finding. You dispose; the system records. The same discipline is why a report's conclusion is human-authored (see §06).

06Export the audit report

The report is the deliverable you hand an auditor as evidence for SOC 2 (CC4.1, CC7.x) and ISO 27001 (A.8.8, A.8.29) controls.

On the Repository detail page (a Report section) or the Compliance screen's export panel, use Export PDF, Export CSV, or Export JSON.

PDF — a multi-page report: scope, test date, findings by severity with CWE/OWASP/CVE/EPSS/KEV/location/evidence/remediation/receipt, methodology, a machine attestation, a control-evidence mapping, and a disclaimer. It is verifiable — its content is Ed25519-signed when a signing key is configured, and honestly marked unsigned when not.
CSV — one row per finding, for GRC tools (Vanta, Drata, …).
JSON — the full structured report for your own automation.

Requires compliance.report.generate (Security / Auditor / Admin / Owner seats).

Two honest notes

The report is point-in-time — a pentest is evidence within a Type 2 period, dated by the scan/commit, not a period attestation. And the pentester conclusion is human-authored: the machine never writes it, so a fresh export reads "awaiting attester" until a person signs off.

07Compliance & audit

Compliance — scope, disclaimer, acceptance and traceability panels, plus per-repository report export. An org-wide signed handover bundle and a feed-licence ledger are not built yet and show as unavailable rather than fake controls.
Audit log — read and verify the tamper-evident audit trail and its receipts. Requires org.audit.read (Auditor / Admin / Owner).

08Ask questions about your code API only

Assay can answer questions grounded in your indexed code — retrieval-augmented, cited, and it refuses rather than inventing when it has no context. There is no chat screen in the console yet.

POST /v1/repositories/{id}/conversations/{conversation_id}/messages — ask; the answer streams back, grounded in that repository's current snapshot.
Requires repo.chat and a configured LLM provider for the org (§10).

09Authorized recon engagements API only

Assay's offensive engine is recon-only and strictly authorized — nothing touches a target without a live, verified authorization grant covering it. This is deliberately gated, and API-only today.

Propose a grant — POST /v1/orgs/{org_id}/authorization-grants (authorization.grant.propose). You get a DNS-TXT challenge (asy-site-verification=<uuid>) to publish, proving you control the target.
Approve the grant — POST …/authorization-grants/{id}/approval (authorization.grant.approve, step-up; the approver must differ from the proposer). Moves it pending → verified.
Trigger the engagement — POST /v1/repositories/{id}/engagements with the target. Runs only if a verified grant already covers it (else 409).

Honest gaps

The HTTP step-up (fresh MFA) mechanism is not fully wired yet, so approvals and engagement triggers currently return 401 step_up_required in practice. And beyond-recon (exploitation, fuzzing) is held behind a counsel gate — a human decision, never automatic.

10Admin: what an admin configures

Task	Where	Permission
Teams & members	Console → Teams	`org.team.manage`
Single sign-on (OIDC)	Console → Single sign-on	`org.sso.configure` · step-up
LLM provider (chat & recon) API only	`PUT /v1/orgs/{org}/llm-provider`	`llm.provider.configure` · step-up
Org settings	Console → Settings	`org.settings.update`
Usage / billing	Console → Usage	`org.billing.read`

Secrets are write-only: the SSO client secret and the LLM API key are never returned by a read (you see only "is set"). The Credentials settings page is informational only — that API is not built yet.

11Roles — who can do what

Your organization seat sets what you can do; a per-repository grant can only narrow it, never widen it (effective access = role ∩ grant).

Role	Can
Owner	Full authority; the only role that can delete the org.
Admin	Everything except org-delete and support-impersonation consent.
Security	Reads everything, triages findings, approves egress; no credential custody, no membership changes.
Member	The default working seat: import repos, scan/index, read source, chat, triage findings on reachable repos.
Auditor	Reads/exports the audit trail and generates compliance reports; no source, no chat.
Billing	Sees the org and its costs only; no repository access.
Guest	Read-only "customer-end" seat; with a chat-only grant, the wiki/chat and nothing else.
Service account	Non-human principal that indexes/scans/reads; never triages, administers, or exports.

A plain member cannot manage SSO/LLM/credentials, read the audit trail, generate compliance reports, approve grants, trigger engagements, or delete the org — those are admin/owner/security/auditor capabilities.

12Honest limits (today)

API-only, no console screen yet: chat / wiki (RAG), recon engagements, authorization grants, LLM-provider config, SBOM ingest.
Not built: self-service credential management; an org-wide signed handover bundle; RP-initiated (provider-side) logout; a fully wired HTTP step-up mechanism.
Import is one repo per clone URL (no git-host "connect & pick").
The pentester conclusion on a report is human-authored by design — an export reads "awaiting attester" until a person signs it.