Security & data

Before you add a security tool to your repository, you should know what it reads, where that information goes, and how to switch it off.

Ferralon comes in two parts that build on each other:

  1. Ferralon Assay (free) analyzes your entire codebase in your own CI and finds where your code can reach a known vulnerability.
  2. Ferralon Arc (early access) takes the candidates Assay finds and proves them.

Assay on its own keeps the analysis in your runner. Linking it to the console sends Ferralon an assessment of each scan. Arc then fetches your source to build and test it. This page follows that order.

Free: scanning runs in your CI

Ferralon Assay adds one file to a repository: the workflow .github/workflows/ferralon-assay.yml, through a pull request you choose to merge. The scan runs on your runner with that workflow's own token, and the analysis itself never runs on Ferralon's servers.

To do its work, a run downloads three things:

  • one scanner release, pinned and checked against its SHA-256 before it runs;
  • your language's usual public package and advisory services (for Go, the module proxy and the Go vulnerability database), which receive module names and nothing from your source;
  • Ferralon's published advisory corpus, a public dataset.

Every action in the workflow is pinned to a full commit SHA.

Free, with the console: what reaches Ferralon

One setting in the workflow decides whether a scan talks to Ferralon at all: FERRALON_LINK_TO_CONSOLE in the job's env:, which the setup pull request sets to true. While it is true, a run makes three requests, to the three addresses written out in the workflow file:

  • The scan window, at the start of every run. One request asks your console which scan window to use. It sends the run's GitHub OIDC token, which identifies the repository, its owner and the run, and nothing else: no source code. What comes back is the window and its source, either your console's setting or Ferralon's default. The run writes both to its log and summary.
  • The assessment, for the branch you track. That is your default branch, unless .github/ferralon.yml names another. It holds your dependencies, the advisories that matched them, and for a reachable finding, the function names and file:line where your code reaches the affected package. This is what lets the console show the repository alongside your other repositories.
  • A run record, every run. The repository's owner and name, the commit SHA, and the scanner version. The same channel tells the scan when the Ferralon App has been uninstalled, so the workflow can remove itself.

None of the three carries the contents of your source files.

Set FERRALON_LINK_TO_CONSOLE to false, or delete the line, and none of the three calls is made. The scan uses the window written into the workflow file without asking. The scan, its pull-request comment, the dashboard issue, the report and code-scanning alerts all keep working. You give up three things: self-removal, because the uninstall signal arrives on the run-record channel; Arc proofs, which start from these assessments; and windows you save in the console, because the run no longer asks for one. The assay step's link-to-console input only passes this same value on, so the env: line is the switch.

The workflow file itself documents every address a run contacts, so a reviewer can confirm all of this from the file in their own repository.

Moving to Arc

The assessments that reach the console are also where Arc starts: it proves the candidates in them. To move from Assay to Arc, keep FERRALON_LINK_TO_CONSOLE on and request early access from the console. Admission turns on proving for your organization. From then on, each assessment your workflow posts is checked for new candidates, and Arc starts a proof for each one. That applies to every repository where the Ferralon App is installed, and the workflow in your repository does not change.

Arc: what a proof uses

Proofs run only for organizations admitted to Ferralon Arc. For each candidate:

  • Your source is fetched at the analyzed commit, through the Ferralon GitHub App and its installation permissions, onto a single-use machine. The machine is deleted when the run ends.
  • The advisory corpus is verified against its signature before the machine uses it. A release that fails verification stops the run.
  • An AI model service (Anthropic) helps write the exploit and the patch.

The proof result and the evidence for each step are stored with your organization's results in Ferralon and shown in your console. The patch goes into the pull request Arc opens in your repository, with links to that evidence.