Learn

Concepts

The nouns Arachne uses everywhere: organisations and roles, projects, findings, advisories, jobs, modes, approvals, the evidence bundle, and plans and usage.

Organisations and roles#

Every person gets a personal organisation at first sign-in. All data (projects, findings, jobs, approvals) belongs to an organisation, and you only ever see the organisation you are acting in. Your role there decides what you can do, in the web app and over MCP alike:

Over MCP the read tools (advisories, repos_affected, propose_version, job_status) need only read access, so every role can use them; fix_submit needs the submit permission and pr_open the PR permission. See Tools reference.

Projects#

A project is one connected repository plus its settings. Connecting is cheap and read-only; it counts towards your plan's repository limit (3 on Hatchling). Re-saving an already connected repository is not a new connection.

Connecting repositories#

A project comes from any source control: GitHub, GitLab (gitlab.com or a self-hosted host your operator allows), Bitbucket Cloud, Azure DevOps, or Any Git (a public HTTPS clone URL). Each connection records its provider, the normalised repository, whether it is public or private (detected anonymously when you connect) and whether a token is stored.

• Public repositories are scanned and fixed with no token. Verified fixes download as a .patch file.
• A token (owners and admins only) lets Arachne open pull/merge requests on that one repository: GitHub fine-grained token with Contents + Pull requests read and write; GitLab project token with api; Bitbucket repository access token with repository:write + pullrequest:write; Azure DevOps PAT with Code (Read & write). GitLab, Bitbucket and Azure DevOps pull requests are beta: verified against the documented APIs, not yet against a live account.
• Private repositories: connect with a token to open PRs; scanning and automatic fix jobs currently support public repositories only (the fix-job build never receives credentials), and Arachne answers a private scan or fix with a clear refusal.

Step by step, with the token scopes per provider: Quickstart, Connecting repositories.

Findings#

A finding is one vulnerable dependency in one project: package, version, whether it is declared directly, the advisory, a summary, the fix state (fixed with fixed_versions, or no_fix_known), KEV and EPSS, and the advisory's source and licence. Findings come from declared dependencies in your manifests and lockfiles; nothing is installed during a scan. The fix job later checks the installed tree independently.

Advisories, KEV and EPSS#

An advisory is a published vulnerability record (OSV / GitHub Security Advisory ids such as GHSA-j8r2-6x86-q33q, with aliases such as CVE-2023-32681), with affected version ranges per ecosystem and package. Arachne keeps its own copy, licence-filtered and attributed, and enriches CVE aliases with:

• KEV: listed in CISA's Known Exploited Vulnerabilities catalogue, i.e. exploited in the wild. Treat these first.
• EPSS: the Exploit Prediction Scoring System probability (0 to 1) that the CVE is exploited in the next 30 days. Arachne reports the highest EPSS among an advisory's CVE aliases.

The database is served from its last good sync. When sources have not synced for 48 hours the app shows a "data stale" banner.

Jobs#

A job is one sandboxed fix attempt for a project. It has a status (queued, running, done, dead) and, when done, an outcome (verified, needs_approval, failed, unverifiable, no_fix_available, nothing_to_fix). Each job is created with an idempotency key: submitting the same key again returns the existing job and never reserves a second use. Jobs are retried on infrastructure failure up to 3 attempts, then marked dead. See the job lifecycle diagram.

Modes#

Each project stores a mode, one of:

Approvals#

An approval is a pending human decision attached to a job. There are two kinds:

• open_pr: created when a job ends verified. Approve it to allow the PR; reject it to drop the fix and return the use.
• major_bump: created when the only safe version is a new major version (needs_approval). Approving queues a re-run that may take the major bump; the held use moves to the re-run. If the re-run cannot be queued (quota, frozen organisation) the approval goes back to pending.

Approvals are decided in the web app by an owner or admin. No MCP tool can approve; pr_open refuses with not_approved until someone has.

The evidence bundle#

Every finished job keeps its evidence, and the PR body is rendered from it:

• Outcome and confidence, for example verified / high: deterministic dependency-only change.
• Plan: each package's current and chosen version, status, major-bump flag, the advisories it fixes, and the candidate versions that were rejected with the reason.
• Gate results: the five gates with status and a one-line note, plus the test delta (baseline vs after, lost tests) and the independent rescan's inventory source.
• Diff: the exact file changes that will be pushed, and nothing else.

Plans and usage#

Plans belong to a person, not an organisation, so creating more organisations never raises a limit. A use is one opened pull request (1 PR = 1 use): reserved when a fix is submitted, consumed when the PR opens, released otherwise. Allowances reset at 00:00 UTC on the first of each month.

When you run out, the refusal (quota_exhausted, or payments_not_enabled on a metered plan while payments are off) carries resets_at and three options:

• request_more: "Request more uses" in the app sends a short message; an operator grants extra uses for the month or declines. One pending request at a time.
• wait: the allowance resets at resets_at.
• upgrade: paid plans with metered overage. Payments are not enabled yet, so this currently says so.

Your usage is shared across all of your accounts that use the same verified email or identity, so a second sign-up does not reset it.