- the
scanoss/pre-commit-hookspre-commit hook checks your code each time you commit scanoss-py, a command-line scanner, scans your code on your own machine and saves the results in.scanoss/results.json- Code Compare, a desktop app, is where you review what the scan matched, and it saves your decisions in a file in your repository called
scanoss.json - the SCANOSS code-scan GitHub Action scans each pull request and reports three checks on it
- Dependency-Track, a separate open-source tool, holds your policies, the code that breaks them, and the exceptions you’ve allowed
You move over in five phases:
- Connect and scan. Connect your repositories to Earnie and run a first scan.
- Bring over your identifications. Earnie reads the decisions already saved in your
scanoss.json. - Rebuild your policies. Recreate your Dependency-Track rules in Earnie.
- Switch the gate. Replace the old pull-request checks with Earnie’s, one repository at a time.
- Move developer tooling. Replace the pre-commit hook and install the Earnie CLI.
Key Terms
These words come up throughout the guide:Before You Start
A few things the old tools did have no exact match in Earnie. Check these against your setup before phase 1:- CWE policies can’t be rebuilt. CWE is a list of software weakness types. Earnie has no CWE data, so a Dependency-Track rule based on CWE has no equivalent. See the policy table.
- Policies don’t move over automatically. There’s no tool to import Dependency-Track policies, so you recreate them by hand in phase 3.
- Each exception covers one finding. A component that shows up in many files needs a separate Policy Approval for each finding a policy flags.
- You can’t limit a project to part of a repository. In a monorepo, use skip patterns to leave out the parts you don’t want scanned.
bom.ignoreinscanoss.jsonisn’t applied. It hid matches from the results. Earnie shows those matches as findings for you to decide.
What Replaces What
Earnie also gives the same policies to AI coding agents, such as Claude Code or Cursor, while they write code. The old tools have nothing like this. See Earnie MCP.
The Five Phases
Each phase ends with a Done when check. Finish it before you start the next phase.Phase 1: Connect and Scan
Set up your Earnie organisation, then connect your Git provider and import the repositories you want Earnie to check. Each repository becomes a project.- GitHub, including GitHub Enterprise Server, connects through the Earnie GitHub App.
- GitLab, on gitlab.com or self-managed, connects with an access token.
Expect a backlog on the first full scan. If the GitHub Action only ever
scanned the files each pull request changed, nothing has checked your whole
repository before. The first full scan can find things the old tools never
showed you. That’s not a sign that something broke. Plan time to review them.
Phase 2: Bring Over Your Identifications
The decisions you made in Code Compare live in each repository’sscanoss.json. Earnie reads that file on every scan, so you don’t need to import it. Each kind of entry carries over like this:
An entry applies only to a component the scan actually found, and an entry with a
path applies only inside that path. An entry never adds a finding. Earnie names the scanoss.json file as the source of each decision it records this way. See Component overrides.
Decide what’s left in Earnie’s Review Workspace. In Components mode, Bulk decide records one decision for every undecided finding of a component at once.
Done when: no project shows findings your team has already decided, and your reviewers agree that what’s left open is real work.
Phase 3: Rebuild Your Policies
Recreate your Dependency-Track policies as Earnie policies. Earnie can’t import them, because the two tools describe rules differently. Use the policy table to translate each rule, and Violation States and Exceptions to choose what each one does: Block, Require approval, or Warn. Where you can, start from Earnie’s built-in templates. They cover the rules most teams use, and they’re quicker to review than a rule you write yourself:
Copyleft licences, such as the GPL, require you to share your own source code under the same licence in some cases. Weak copyleft licences, such as the LGPL, ask for less.
Where your organisation has cryptography or AI provenance scanning, more templates are available. See Cryptography and AI provenance.
In Earnie, a policy belongs to your whole organisation, and you attach it to the projects it should check. A rule you had for one repository becomes a policy attached to one project. You can’t change a shared policy for just one project. To use a different rule there, clone the policy and change the copy. See Where a policy applies.
Done when: for each project, Earnie’s gate gives the same result as Dependency-Track on the same code, or your policy owner has written down and accepted each difference. To compare, list the policies and what each one flags. These commands only read, and change nothing:
Phase 4: Switch the Gate
Your Git provider decides which checks must pass before a pull request can merge. On GitHub, this is branch protection, and each check it waits for is a required status check. In this phase, you make Earnie’s check the required one. For each repository, make these three changes together:- In branch protection, add Earnie as a required status check.
- In branch protection, remove the three
Policy Check: *required checks. - In one pull request, delete the code-scan Action workflow and its Dependency-Track upload step, then merge it.
On a pull request, only the findings the pull request added decide the check. The summary comment also lists findings that were already on the default branch, but they don’t block the pull request.
A neutral check means Earnie couldn’t compare, not that the pull request passed. It appears in two cases:
- No baseline to compare against; result is not conclusive: Earnie has no completed scan of the default branch yet. Scan the default branch.
- Base branch moved; result is not conclusive: the default branch has changed since the pull request was scanned. Push a commit, or run the scan again.
Phase 5: Move Developer Tooling
Install the Earnie CLI wherever developers or pipelines need it:earnie auth login. See Earnie CLI.
Replace the pre-commit hook. If your repositories use the pre-commit framework, replace the scanoss/pre-commit-hooks entry in .pre-commit-config.yaml:
pre-commit install --install-hooks and pre-commit run earnie once, so the framework downloads and checks the pinned CLI before the first commit. If you don’t use the framework, run earnie hook install in each copy of the repository instead.
Either way, the hook runs earnie scan staged --format hook on every commit. It checks the changes you’ve staged in Git, not every file you’ve edited, and runs a Self-check. A Self-check never adds findings to the project or changes its results.
If the hook can’t run the check, for example because of a network or sign-in error, or because it took longer than 60 seconds, it reports the problem and lets the commit through. An Operator or Admin can make these failures stop the commit instead, with Pre-commit technical failures in the project’s Scan Configuration. A developer can do the same for their own commits by setting
EARNIE_HOOK_FAIL_CLOSED=1. See When the Check Can’t Run in Checking before you commit.
Optionally, connect AI coding agents. earnie mcp setup connects Claude Code, Cursor, VS Code, or Codex to Earnie, so the agents follow your policies while they write code. See Connecting an AI client.
Finally, uninstall Code Compare.
Done when: no repository’s developer instructions still mention scanoss/pre-commit-hooks, Code Compare, or scanoss-py, and a test commit in each repository shows up as a Self-check in Earnie.
Dependency-Track to Earnie Policies
Use this reference in phase 3, if you’re the person rebuilding the policies. A Dependency-Track policy is made of conditions, and each condition checks one subject, such as a licence or a severity. This table covers the fifteen subjects of Dependency-Track’s classic policies. Dependency-Track 5.0 also has expression-based policies, which this table doesn’t cover. Rewrite each of those by hand. Earnie policies are written in CEL (Common Expression Language), but Earnie and Dependency-Track describe components differently, so you can rarely copy an expression across unchanged. List the policies in your own Dependency-Track first, and note its version. Use this table to translate what you find, not to decide what you have.
Earnie also has fields that Dependency-Track doesn’t, which you may want to use: Dual Licensed, Patent Clauses, License Data Source, Component Status, Match Percentage, the finding’s State and Domain, and the cryptography and AI provenance fields where your organisation has them.
earnie policy show <policy-slug> prints the exact expression a policy runs.
Violation States and Exceptions
In Dependency-Track, each policy marks a violation asINFO, WARN, or FAIL. In Earnie, each policy has an action instead: Warn, Require approval, or Block.
Start from what your pipeline does today. The SCANOSS GitHub Action failed on any Dependency-Track violation, whatever its state, so INFO, WARN, and FAIL all turned the check red. In that setup, every violation blocks.
If your CI read Dependency-Track’s results directly instead, through its API or project badge, it could treat the states differently and block on FAIL only. Check which setup you’re replacing before you map anything.
There’s no automatic translation. The action you choose decides how strict your gate is, so choose it with whoever owns your policies:
Whichever you choose, write down the mapping and why you chose it. Your build behaves differently either way, and you’ll want the reason the first time a check turns green unexpectedly.
A Policy Approval records:
- a justification category, based on the CISA VEX justifications for why a risk doesn’t apply
- a written reason
- who approved it
- an optional expiry date
- any later revocation
What Changes for Your Team
- One check, not three. Branch protection waits for Earnie instead of the three
Policy Check: *checks. - Every decision has a name, a time, and a reason. A
scanoss.jsonentry recorded none of those. Earnie records all three for every triage decision and Policy Approval. See Audit log.earnie scan audit <scan-id>prints the history of one scan: when it started, its gate, approvals that changed it, and what Earnie posted to the pull request. - You make decisions in Earnie, not in files. Instead of editing
scanoss.jsonand pushing, you decide the finding or request an approval in Earnie, and the pull request updates without a push. Changing the code itself still needs a push, so Earnie can scan the change. - No local results file. Earnie doesn’t write
.scanoss/results.json. The hook prints a short summary and a link, and the full results are in Earnie. Remove.scanoss/from the repository and from.gitignore. - No upload to Dependency-Track. If other tools also send results to Dependency-Track and you want to keep using it, upload Earnie’s SBOM yourself. Run
earnie export --bom-format cyclonedx --output sbom.jsonin a pipeline step, then upload the file in your own step. Earnie has nothing like Dependency-Track’s project versions: one Earnie project is one codebase for its whole life. - Scanning moves off developers’ machines. Instead of scanning locally with
scanoss-py, the CLI sends your code to your Earnie environment, where it’s scanned and checked against your policies. By design, there’s no offline mode. - Fewer comments on each line. Earnie comments only on lines the pull request added, only for findings of Medium severity or higher, and at most ten times per review by default. Everything else goes in the summary comment. See Inline comments on the changed lines.
- Posting results is separate from the result. If GitHub or GitLab refuses Earnie’s comment or check, the scan’s result still stands, and the scan’s page offers Retry publication. Retrying doesn’t run the scan again.
- Results appear on the pull request and in Earnie only. Earnie doesn’t yet send policy notifications by email or chat. If you relied on Dependency-Track’s notifications, plan a replacement.