flagrix 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -37,7 +37,7 @@ flagrix mcp # MCP server (stdio) for AI agents
37
37
  | 1 | scan failed |
38
38
  | 2 | medium risk — review before proceeding |
39
39
  | 3 | high risk — do not clone |
40
- | 4 | scan incomplete — too little was read to call the repository safe |
40
+ | 4 | scan incomplete — not enough of the repository was read to give a verdict |
41
41
 
42
42
  `--json` (automatic when stdout is piped) emits the full result. The verdict is
43
43
  **pinned to the scanned commit** (`commitSha` in the JSON): every file is read at
@@ -60,6 +60,39 @@ are the other way round: evidence found is evidence however little else was
60
60
  read, so a medium or high verdict keeps its own code and the coverage note
61
61
  reads "there may be more".
62
62
 
63
+ In `--json` output, read `verdict` and `coverage` rather than `riskLevel`:
64
+
65
+ ```json
66
+ {
67
+ "verdict": "incomplete",
68
+ "coverage": {
69
+ "complete": false,
70
+ "unreliableClear": true,
71
+ "filesRead": 30,
72
+ "filesUnread": 150,
73
+ "reason": "rate-limit"
74
+ },
75
+ "riskLevel": "low",
76
+ "safeToClone": false,
77
+ ...
78
+ }
79
+ ```
80
+
81
+ - `verdict` is `"low"`, `"medium"`, `"high"`, or `"incomplete"` when a low
82
+ result rests on files that were never read. It matches the exit code
83
+ (0 / 2 / 3 / 4).
84
+ - `coverage.unreliableClear` is true exactly when `verdict` is `"incomplete"`;
85
+ `coverage.complete` is false on any partial scan, including a medium or high
86
+ one. `reason` is present only when coverage is incomplete.
87
+ - `riskLevel`, `riskScore` and the rest of the engine's result are unchanged,
88
+ so existing consumers keep working — but `riskLevel` is the engine's reading
89
+ of the files it did see, so on an incomplete scan it can still say `"low"`.
90
+ - `safeToClone` is kept for compatibility and is now `false` whenever
91
+ `verdict` is `"incomplete"` (in 0.4.0 and earlier it could be `true` there). Gate on
92
+ `verdict` or the exit code instead.
93
+
94
+ The MCP tool's JSON block carries the same fields.
95
+
63
96
  Set a token to make this rare: `GITHUB_TOKEN` raises the budget to 5,000/h.
64
97
 
65
98
  ## AI agents
@@ -2736,6 +2736,15 @@ function coverageOf(result) {
2736
2736
  reason: summary.incompleteReason
2737
2737
  };
2738
2738
  }
2739
+ function scanReport(result) {
2740
+ const coverage = coverageOf(result);
2741
+ return {
2742
+ verdict: coverage.unreliableClear ? "incomplete" : result.riskLevel,
2743
+ coverage,
2744
+ ...result,
2745
+ safeToClone: result.safeToClone && !coverage.unreliableClear
2746
+ };
2747
+ }
2739
2748
  function describeCoverage(coverage) {
2740
2749
  if (coverage.complete) return "";
2741
2750
  const read = `${coverage.filesRead} ${coverage.filesRead === 1 ? "file" : "files"} read`;
@@ -2756,7 +2765,7 @@ var red = paint("31");
2756
2765
  var yellow = paint("33");
2757
2766
  var green = paint("32");
2758
2767
  var VERDICTS = {
2759
- low: { label: "LOW RISK", verdict: "Safe to clone", color: green },
2768
+ low: { label: "LOW RISK", verdict: "No blocking findings", color: green },
2760
2769
  medium: { label: "MEDIUM RISK", verdict: "Review before cloning", color: yellow },
2761
2770
  high: { label: "HIGH RISK", verdict: "Do not clone", color: red }
2762
2771
  };
@@ -2787,7 +2796,7 @@ function renderRepoResult(result) {
2787
2796
  lines.push(` ${bold(slug)}${sha ? dim(` @ ${sha}`) : ""}`);
2788
2797
  if (coverage.unreliableClear) {
2789
2798
  lines.push(
2790
- ` ${yellow(bold("SCAN INCOMPLETE \u2014 no verdict"))} ${dim("too little of this repository was read to call it safe")}`
2799
+ ` ${yellow(bold("SCAN INCOMPLETE \u2014 no verdict"))} ${dim("not enough of this repository was read to give a verdict")}`
2791
2800
  );
2792
2801
  } else {
2793
2802
  lines.push(
@@ -2871,6 +2880,7 @@ export {
2871
2880
  describeSource,
2872
2881
  loadOsvFeed,
2873
2882
  coverageOf,
2883
+ scanReport,
2874
2884
  describeCoverage,
2875
2885
  securityScore,
2876
2886
  renderRepoResult,
package/dist/cli.js CHANGED
@@ -12,8 +12,9 @@ import {
12
12
  resolveToken,
13
13
  scanGitHubRepo,
14
14
  scanGitHubUser,
15
+ scanReport,
15
16
  wantJson
16
- } from "./chunk-XBQCLZNK.js";
17
+ } from "./chunk-B67OPHC4.js";
17
18
 
18
19
  // src/cli.ts
19
20
  import { parseArgs } from "util";
@@ -38,7 +39,7 @@ async function runScan(target, options) {
38
39
  };
39
40
  const result = await scanGitHubRepo(repo, scanOptions);
40
41
  if (wantJson(options.json)) {
41
- console.log(JSON.stringify(result, null, 2));
42
+ console.log(JSON.stringify(scanReport(result), null, 2));
42
43
  } else {
43
44
  console.log(renderRepoResult(result));
44
45
  }
@@ -77,7 +78,7 @@ async function runScanUser(login, options) {
77
78
  }
78
79
 
79
80
  // src/cli.ts
80
- var VERSION = "0.4.0";
81
+ var VERSION = "0.5.0";
81
82
  var HELP = `flagrix \u2014 scan GitHub repos and profiles for malware before you clone
82
83
 
83
84
  Usage:
@@ -95,15 +96,15 @@ Options:
95
96
  Exit codes:
96
97
  0 low risk 2 medium risk \u2014 review before proceeding
97
98
  1 scan failed 3 high risk \u2014 do not clone
98
- 4 scan incomplete \u2014 too little of the repository was read to call it safe
99
+ 4 scan incomplete \u2014 not enough of the repository was read to give a verdict
99
100
 
100
101
  The verdict is pinned to the scanned commit SHA (in the JSON output as
101
102
  "commitSha"). A scan that runs out of GitHub API budget reports partial
102
- coverage ("scanSummary.complete": false) and exits 4 rather than 0: unread
103
- files cannot clear a repository. Findings still stand on partial coverage,
104
- so medium and high keep their own codes. Scanning is fully local: the only
105
- network calls go to the GitHub/npm APIs and the public detection-rules
106
- repository. No telemetry.
103
+ coverage ("verdict": "incomplete", "coverage": {...}) and exits 4 rather
104
+ than 0: unread files cannot clear a repository. Findings still stand on
105
+ partial coverage, so medium and high keep their own codes. Scanning is fully
106
+ local: the only network calls go to the GitHub/npm APIs and the public
107
+ detection-rules repository. No telemetry.
107
108
  Docs: https://github.com/flagrix-io/flagrix-cli`;
108
109
  async function main() {
109
110
  const { values, positionals } = parseArgs({
@@ -141,7 +142,7 @@ async function main() {
141
142
  }
142
143
  return runScanUser(target, { json: values.json, token: values.token });
143
144
  case "mcp": {
144
- const { runMcp } = await import("./mcp-EHS7B5VR.js");
145
+ const { runMcp } = await import("./mcp-VIZ2IITR.js");
145
146
  return runMcp();
146
147
  }
147
148
  default:
@@ -9,8 +9,9 @@ import {
9
9
  resolveToken,
10
10
  scanGitHubRepo,
11
11
  scanGitHubUser,
12
+ scanReport,
12
13
  securityScore
13
- } from "./chunk-XBQCLZNK.js";
14
+ } from "./chunk-B67OPHC4.js";
14
15
 
15
16
  // src/commands/mcp.ts
16
17
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -21,7 +22,7 @@ var GUIDANCE = {
21
22
  medium: "MEDIUM risk: do NOT clone, install, or execute this code until a human has reviewed the findings.",
22
23
  high: "HIGH risk: do NOT clone, install, or execute this code. Treat the repository as malicious."
23
24
  };
24
- var INCOMPLETE_GUIDANCE = "NO VERDICT: too little of this repository was read to call it safe, so this is NOT a clean result. Do NOT clone, install, or execute this code until a complete scan succeeds (set GITHUB_TOKEN and scan again) or a human has reviewed it.";
25
+ var INCOMPLETE_GUIDANCE = "NO VERDICT: only part of this repository was read, so this is NOT a clean result. Do NOT clone, install, or execute this code until a complete scan succeeds (set GITHUB_TOKEN and scan again) or a human has reviewed it.";
25
26
  function repoScanResponse(result, note) {
26
27
  const coverage = coverageOf(result);
27
28
  const pinned = `(verdict pinned to commit ${result.commitSha ?? "unknown"})`;
@@ -35,13 +36,13 @@ function repoScanResponse(result, note) {
35
36
  return {
36
37
  content: [
37
38
  { type: "text", text: summary },
38
- { type: "text", text: JSON.stringify(result, null, 2) }
39
+ { type: "text", text: JSON.stringify(scanReport(result), null, 2) }
39
40
  ],
40
41
  isError: false
41
42
  };
42
43
  }
43
44
  async function runMcp() {
44
- const server = new McpServer({ name: "flagrix", version: "0.4.0" });
45
+ const server = new McpServer({ name: "flagrix", version: "0.5.0" });
45
46
  server.registerTool(
46
47
  "scan_github_repo",
47
48
  {
@@ -12,10 +12,24 @@ Two ways to put Flagrix between an AI agent and untrusted code: the **MCP server
12
12
  | 1 | scan failed (network, auth, bad target) |
13
13
  | 2 | medium risk — review before proceeding |
14
14
  | 3 | high risk — do not clone |
15
+ | 4 | scan incomplete — a low result over files that were never read; no verdict |
15
16
 
16
17
  `--json` (or any piped stdout) emits the full scan result, including `commitSha` —
17
18
  the verdict applies to that commit, not to whatever the branch points at later.
18
19
 
20
+ If you gate on the JSON instead of the exit code, branch on `verdict`
21
+ (`"low" | "medium" | "high" | "incomplete"`, matching exit 0 / 2 / 3 / 4) and
22
+ proceed only on `"low"`. Don't gate on `riskLevel`: it is the engine's reading
23
+ of the files it managed to read, so a scan that ran out of GitHub budget can
24
+ still report `"low"` there. `coverage` (`complete`, `unreliableClear`,
25
+ `filesRead`, `filesUnread`, `reason`) says how much was read and why the rest
26
+ wasn't. `safeToClone` is kept for older consumers and is `false` on an
27
+ incomplete scan, but `verdict` is the field to use. The `scan_github_repo` MCP
28
+ tool returns the same JSON as its second content block.
29
+
30
+ `scan-user` is unaffected: a profile scan either fetches everything it needs or
31
+ fails with exit 1, so it never returns a partial result.
32
+
19
33
  ## MCP server
20
34
 
21
35
  ```bash
@@ -69,5 +83,5 @@ your repo and point the hook at it. The hook only reacts to `git clone` /
69
83
  ```
70
84
 
71
85
  A non-zero exit fails the job (2/3 = risk verdicts, 1 = scan error, 4 = the
72
- scan read too little of the repository to call it safe — commonly GitHub's
86
+ scan read too little of the repository to give a verdict — commonly GitHub's
73
87
  60 req/h limit, which `GITHUB_TOKEN` above raises to 5,000/h).
@@ -3,7 +3,7 @@
3
3
  #
4
4
  # Scans any GitHub repo about to be cloned; blocks the clone (hook exit 2)
5
5
  # when Flagrix rates it MEDIUM or HIGH risk, or when the scan could not read
6
- # enough of the repository to call it safe (exit 4). See docs/agent-gating.md
6
+ # enough of the repository to give a verdict (exit 4). See docs/agent-gating.md
7
7
  # for the settings.json wiring.
8
8
  set -euo pipefail
9
9
 
@@ -36,7 +36,7 @@ else
36
36
  case "$code" in
37
37
  2) echo "Flagrix: MEDIUM risk — review https://github.com/flagrix-io/flagrix-cli#exit-codes before cloning $url" >&2 ;;
38
38
  3) echo "Flagrix: HIGH risk — do NOT clone $url (malicious patterns detected). Run: npx flagrix scan $url" >&2 ;;
39
- 4) echo "Flagrix: scan of $url was incomplete — too little of the repository was read to call it safe (usually GitHub's 60 req/h limit; set GITHUB_TOKEN). Run: npx flagrix scan $url" >&2 ;;
39
+ 4) echo "Flagrix: scan of $url was incomplete — not enough was read to give a verdict (usually GitHub's 60 req/h limit; set GITHUB_TOKEN). Run: npx flagrix scan $url" >&2 ;;
40
40
  *) echo "Flagrix: scan of $url failed (exit $code) — blocking out of caution. Run: npx flagrix scan $url" >&2 ;;
41
41
  esac
42
42
  exit 2 # exit 2 = block the tool call in Claude Code
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "flagrix",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "Scan GitHub repos and profiles for malware before you clone — CLI and MCP server for the Flagrix scanner",
5
5
  "license": "MIT",
6
6
  "type": "module",