Review Fallow security findings with Jev.
An explanation for each verdict, with uncertain findings left for you to review.
Quickstart · Configuration · Example report · Evaluation
fallow security flags JavaScript and TypeScript code
that might be vulnerable. fallow-verdict asks Jev to
assess each finding using the surrounding code, then gives you a report with a
reason for each verdict. Uncertain findings stay in the report for you to review.
You need Node.js 22.18 or newer and a Jev API key to request assessments. Install the preview in the project you want to review:
cd /path/to/project
npm install --save-dev fallow-verdict fallow
npx fallow-verdict init
npx fallow-verdict run --dry-runinit creates the config and adds the review data directory to .gitignore.
The dry run scans the project and estimates the cost without contacting Jev.
Set TYPESAFE_API_KEY through your shell or secret manager, keeping the value out
of the config file. Then run:
npx fallow-verdict run --show-dismissedResults appear in the terminal and in .fallow-verdict/report.md, with a JSON
export at .fallow-verdict/verdicts.json. A completed run can exit with code 1
when it finds a likely vulnerability.
| Verdict | Meaning |
|---|---|
survivor |
The supplied evidence supports a likely vulnerability. Check the code before acting on a suggested fix. |
dismissed |
The assessment meets the dismissal rules and gives a reason, such as a protection that blocks the input. |
needs-human-review |
The assessment is uncertain, evidence is missing, or a rule requires human review. |
Each finding includes its file and line. Percentages are Jev's estimates of exploitability; expand a finding in the Markdown report to inspect its recorded decision. See an example report.
Jev answers fixed questions about whether an attacker can exploit the code in each finding. Rules in this package turn those answers into a verdict. Dismissing a real vulnerability would hide it from the main review list, so dismissal requires:
- An estimated chance of exploitation below the threshold for the finding's severity. High-severity findings have a stricter threshold.
- Answers that support a specific reason for dismissal.
- Readable evidence at every requested source location, without shortening it to fit the request budget.
- No flag from Jev that the code contains text trying to influence the assessment.
Jev can misread a protection or miss a misleading comment. Relevant code may also sit outside the supplied excerpts. The questions and decision rules document how these answers are used.
The export uses fallow-security-verdicts/v1 and keeps Fallow's finding IDs.
fallow security survivors validates the exported verdicts.
An assessment sends Fallow's finding metadata and numbered code excerpts to Jev. The excerpts include the flagged operation and checks Fallow found in related files. The evidence collector refuses paths outside the project root, including paths reached through symlinks.
Local state in .fallow-verdict/ contains finding evidence and raw answers.
Evidence can include literals from your code, so keep this directory out of Git.
The configured API key is read from the environment and is never written to config
or state. There is no telemetry.
For untrusted repositories, pass a JSON config with --config; JavaScript and
TypeScript config files execute code locally. See privacy for
what is sent and stored, and check Jev's terms before sending proprietary code.
To limit the estimated spend and duration of a run:
npx fallow-verdict run --max-cost-usd 0.10 --max-duration 60The cost limit includes requests already in progress. Actual charges can differ from estimates, including when a request finishes after a timeout. Use the provider's limits for a hard billing cap.
Run the command again to continue unfinished work. Completed assessments are reused while the evidence and questions match and the requested model and endpoint remain unchanged. Pin a model version in the configuration when comparing runs; fresh calls can still give different answers.
Changing decision thresholds reuses stored answers without another Jev call.
report and eval recheck the collected evidence before applying the policy.
Changes outside those excerpts may require --rejudge and a larger
packet.radius. Findings that Fallow no longer reports become resolved.
| Command | What it does | Can call Jev? |
|---|---|---|
init |
Create a config file and add the state directory to .gitignore. |
No |
scan |
Find security candidates with Fallow and save the scan. | No |
judge |
Assess pending candidates and reuse current answers. | Yes |
report |
Write reports from saved results and validate the verdict export. | No |
run |
Run the scan and assessment, then write reports. | Yes |
status |
Show saved results. | No |
eval |
Compare saved results with labels supplied through --labels. |
No |
check |
Check one finding or one file again after an edit. No state. | Yes |
close |
Record a judgment by a person with --reason. |
No |
Use report --format json for a JSON report. Run npx fallow-verdict --help
for all options, including --changed-since to scan changes since a Git reference.
Run npx fallow-verdict <command> --help for the options and exit codes of one command.
An option that a command does not accept exits with 2.
The JSON output of run, report, status, judge and check has an actions array with
the next steps as commands. See JSON output and actions.
| Exit code | Meaning |
|---|---|
0 |
The command completed without a failing verdict. |
1 |
Results meet --fail-on, or evaluation found a dismissed vulnerability. |
2 |
Invalid input, an execution failure, or incomplete assessments. |
3 |
check only: a finding needs a person. |
130 |
The command was interrupted. |
By default, run and report exit with 1 on likely vulnerabilities.
Set --fail-on needs-human-review to also fail when review is needed.
Incomplete reports exit with 2, even with --fail-on off. The scan and
status commands do not fail because of findings. See the CI guide.
--kind similar-code assesses pairs from fallow similar-code instead of security findings.
It is a preview. See similar-code pairs.
check is for an edit loop. It exits 0 when the findings are resolved, dismissed or
closed, and 1 when a finding stands. See check and close.
The skills/ directory holds skills for coding assistants. A skill is a SKILL.md file with
instructions and a references/ directory with details. Each skill uses Fallow to find the
candidates and fallow-verdict to judge them. The skills change with the CLI, so they ship in
this package.
| Skill | What it does | Changes code |
|---|---|---|
fallow-verdict-similar-code |
Merges function pairs that Jev marks safe, then runs the tests | Inside task scope |
fallow-verdict-security-triage |
Reports likely vulnerabilities first, checks each fix | Only on request |
fallow-verdict-review |
Reviews the changed functions before a pull request | No, reports only |
fallow-verdict-rules |
Helps write review rules, and prefers a Fallow rule | No, proposes only |
Each skill runs --dry-run first and shows the cost, and passes --fail-on off. Config,
suppressions, rules, thresholds and close always go to the user. No skill runs
fallow-verdict in a hook.
To install a skill, copy or link its directory into the skills directory that your coding
assistant reads, for example .claude/skills/ or .agents/skills/ in the project:
npm install --save-dev fallow-verdict fallow
mkdir -p .agents/skills
cp -R node_modules/fallow-verdict/skills/fallow-verdict-review .agents/skills/A link keeps the skill in step with the installed version:
ln -s ../../node_modules/fallow-verdict/skills/fallow-verdict-review .agents/skills/.
Plugin packaging for the skills is on the roadmap.
Live Jev runs have covered public Fallow fixtures and OWASP NodeGoat. In the initial evaluation, safe fixed-origin fetches and same-origin redirects still required human review.
The default question profile is generic. The experimental category profile
adds questions for SSRF and open redirects. The
question-profile comparison records where it dismissed
safe examples and where it still required review.
A vulnerability Fallow misses never reaches Jev. These runs also do not establish accuracy on production projects. Use the evaluation guide to measure which safe findings are dismissed and which vulnerabilities remain visible in your own labeled examples.
- Configuration: model settings and decision thresholds.
- Check and close: the edit loop and its JSON contract.
- Review mode: advisory review of risky functions and project rules.
- Similar-code pairs: the
similar-codekind, its policy and its Fallow join. - Responsibilities: what belongs in Fallow and in this package.
- Architecture: evidence collection and stored records.
- Roadmap: planned work and release requirements.