Get started

Quickstart

Sign in, connect a repository, scan it, run a verified fix and open the pull request: the whole loop on the public demo repository in about ten minutes.

This walkthrough uses the public demo repository aadhi0612/arachne-demo, which pins requests==2.30.0. That version is affected by GHSA-j8r2-6x86-q33q (CVE-2023-32681: requests can leak Proxy-Authorization headers to the destination server on redirect), fixed in 2.31.0. The same steps work for your own public repositories once they are on the allowlist (see Current limits).

What you need

An email address you can receive a verification code at.
About ten minutes. A fix job usually starts within a minute and runs for a few minutes in CodeBuild.
One of your three free monthly uses. It is only consumed if you actually open the PR.

Open the appGo to arachne.withaadhi.com/app. You are sent to the sign-in page.
Create an account or sign inSign-in is email and password (Cognito hosted login). New accounts verify their email with a code before the first sign-in; Arachne refuses an unverified email.
Land on the dashboardYou get a personal organisation automatically. The header shows your usage meter, for example 0 of 3 used this month (resets Dec 1, 2026).

2. Connect a repository#

Open the Connect tab and pick your source controlGitHub, GitLab (gitlab.com or an operator-approved self-hosted host), Bitbucket Cloud, Azure DevOps, or Any Git for any other public HTTPS Git server.
Enter the repositoryEither the short form (owner/repo, group/project, workspace/repo, org/project/repo) or paste the repository URL; Arachne normalises both. Any Git takes the https:// clone URL.
Choose accessPublic repository needs no token. Add a token lets Arachne open pull/merge requests; see Connecting repositories for the exact scopes.
Click Connect repositoryArachne checks the address, detects whether the repository is public, and adds it as a project. Connecting never writes to the repository. Hatchling allows 3 connected repos.

Connecting repositories#

Provider	Repository	Token for pull/merge requests	PR status
GitHub	`owner/repo` or URL	Fine-grained personal access token limited to this one repository: Contents read and write, Pull requests read and write (Metadata read is added automatically).	Live-tested
GitLab	`group/project` (subgroups allowed) or URL; optional self-hosted host	Project access token, role Developer or higher, scope `api` (merge requests need the API; `write_repository` alone only covers git push).	Beta
Bitbucket Cloud	`workspace/repo` or URL	Repository access token with `repository:write` and `pullrequest:write`. App passwords are deprecated by Atlassian and not supported.	Beta
Azure DevOps	`org/project/repo` or `https://dev.azure.com/org/project/_git/repo`	Personal access token for that organisation with Code (Read & write) (`vso.code_write`, which covers pushes and creating pull requests). Pull Request Threads is only for comments and is not needed.	Beta
Any Git	`https://` clone URL on a public host name	None: there is no pull request API. Verified fixes are exported as a patch.	Patch only

Beta means the GitLab, Bitbucket and Azure DevOps pull/merge request code is verified against each vendor's documented API request and response shapes with mocked HTTP, not yet against a live account.

Public and private repositories

Private repositories: connect with a token to open PRs; scanning and automatic fix jobs currently support public repositories only. Fix jobs clone anonymously in an isolated build that never receives your token, so a private repository's scan or fix is refused with a clear message instead of failing later.

Tokens are write-only. Each one is stored in AWS Secrets Manager under its own name, used only for the one repository it was added for, and never shown again, logged or written to the audit log. Replace token rotates it; Disconnect deletes it immediately.
Who can do what. Owners and admins connect repositories and manage tokens; members and viewers can see the list.
Addresses are checked. Only https:// on port 443, no user name or password in the URL, no IP addresses or internal host names, and the host must resolve to public addresses (checked again before every clone).

No token? Download the patch#

Every verified fix has a Download patch button on its job page, and Open PR offers it whenever a pull request can't be opened (no token, Any Git, or the provider refused). Apply it from the repository root:

git switch -c remediation/&lt;job-id&gt;
git apply --check arachne-&lt;job-id&gt;.patch &amp;&amp; git apply arachne-&lt;job-id&gt;.patch
git commit -am "Remediate vulnerable dependencies"
git push -u origin HEAD   # then open the pull/merge request as usual

3. Scan it#

On the dashboard, click Findings next to the project, then Scan now. Arachne clones the repository, detects the ecosystem, reads the declared dependencies and matches each against the advisory database. Scans are free and never count against your allowance.

For the demo you should see a row like:

Package	Version	Advisory	Fix	KEV	EPSS
`requests`	2.30.0	GHSA-j8r2-6x86-q33q	2.31.0		(a small probability)

Tip

Findings are sorted most urgent first: anything in CISA's Known Exploited Vulnerabilities list, then by EPSS (the probability of exploitation in the next 30 days).

4. Click "Fix this"#

Fix this appears on findings that have a known fixed version. It queues one fix job for the project: the job plans upgrades for every fixable vulnerable dependency it finds, not only the row you clicked.

Your allowance is checked and one use is reserved (not spent).
The job page opens and refreshes every few seconds: queued → running → done.
The scheduled worker claims the job within about a minute and starts a CodeBuild build for it.

5. Read the evidence#

When the job is done, the page shows the outcome, a confidence label and three sections:

Section	What to check (demo values)
Plan	One row per package: `requests 2.30.0 -> 2.31.0` with status `fix_found`. The resolver picks the lowest version that fixes every known advisory, respects the package-age cooldown and does not jump a major version without asking.
Gates	Five rows, each with a status: `clean_room_reinstall`, `build`, `independent_rescan`, `test_delta`, `policy`. All `pass` means the outcome is `verified`.
Diff	The exact change that would be pushed. For the demo it is a small edit to the dependency manifest (and lockfile, where there is one).

The outcome reads verified with confidence high: deterministic dependency-only change. If you see failed or unverifiable instead, nothing can be opened and your use has already been returned. What each gate checks.

6. Approve, then open the PR#

Approve PRRecords your decision on the job's open_pr approval. (Reject instead and the reserved use goes back.)
Open PRArachne re-checks that the job is verified and approved, pushes a branch named remediation/<job-id-prefix>-<project> with exactly the reviewed files, and opens the pull request. The PR body is the evidence bundle: plan, gate results and confidence.
DoneA "Pull request opened" card links to the PR, and the meter now reads 1 of 3 used. Review and merge it on GitHub as you would any PR.

Warning

Opening the PR is the step that spends a use. Opening the same job's PR again returns the existing PR and does not count twice.

Do the same from your AI assistant#

Everything above except the approval can be driven over MCP: repos_affected scans, fix_submit queues the job, job_status shows the gates, and pr_open opens the PR once you have approved it in the web app. Start with Install & connect.