flagrix 0.3.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,11 +37,64 @@ 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 — not enough of the repository was read to give a verdict |
40
41
 
41
42
  `--json` (automatic when stdout is piped) emits the full result. The verdict is
42
43
  **pinned to the scanned commit** (`commitSha` in the JSON): every file is read at
43
44
  that SHA, so a push mid-scan or after the verdict can't silently invalidate it.
44
45
 
46
+ ### Incomplete scans (exit 4)
47
+
48
+ A repository scan is one tree request plus up to ~200 file reads, and GitHub
49
+ allows 60 requests an hour without a token. When the budget runs out part way
50
+ through, the rest of the repository is never looked at — so a "low risk, no
51
+ findings" result over 30 of 180 files is the absence of looking, not a clean
52
+ bill of health.
53
+
54
+ The result says so (`scanSummary.complete: false`, with
55
+ `scanSummary.incompleteReason` of `"rate-limit"` or `"fetch-errors"`), the
56
+ human output withholds the verdict and the score, and the exit code is **4**
57
+ instead of 0. In CI the exit code is the decision and nobody reads stdout, so
58
+ a gate on `flagrix scan` stops here as it does on any non-zero code. Findings
59
+ are the other way round: evidence found is evidence however little else was
60
+ read, so a medium or high verdict keeps its own code and the coverage note
61
+ reads "there may be more".
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
+
96
+ Set a token to make this rare: `GITHUB_TOKEN` raises the budget to 5,000/h.
97
+
45
98
  ## AI agents
46
99
 
47
100
  ```bash
@@ -55,8 +108,10 @@ Tools: `scan_github_repo`, `scan_github_user`. A Claude Code hook that gates eve
55
108
  ## Tokens & rate limits
56
109
 
57
110
  Unauthenticated scans use GitHub's 60 req/h budget (a scan issues one request per
58
- scanned file, up to ~50). Set `GITHUB_TOKEN` (or `FLAGRIX_GITHUB_TOKEN`, or
59
- `--token`) to raise it to 5,000/h and to scan private repositories.
111
+ scanned file, up to ~200). Set `GITHUB_TOKEN` (or `FLAGRIX_GITHUB_TOKEN`, or
112
+ `--token`) to raise it to 5,000/h and to scan private repositories. A scan that
113
+ runs out of budget reports partial coverage and exits 4 — see
114
+ [Incomplete scans](#incomplete-scans-exit-4).
60
115
 
61
116
  ## Privacy
62
117
 
@@ -494,6 +494,14 @@ function maskStringLiterals(content) {
494
494
  }
495
495
 
496
496
  // node_modules/@flagrix/scanner-core/dist/github/api-error.js
497
+ function isRateLimitResponse(response) {
498
+ if (response.status !== 403 && response.status !== 429)
499
+ return false;
500
+ return response.headers?.get("x-ratelimit-remaining") === "0" || response.headers?.get("retry-after") !== null;
501
+ }
502
+ function githubNotFoundError(hasToken) {
503
+ return hasToken ? new Error("Your GitHub token can't see this repository \u2014 it may have expired, or it may not include this repo. Check it in Flagrix settings (404).") : new Error("This appears to be a private repository. To scan private repos, add a GitHub personal access token in Flagrix settings.");
504
+ }
497
505
  async function githubApiError(response, fallback = "GitHub API error") {
498
506
  let apiMessage = "";
499
507
  try {
@@ -1032,8 +1040,8 @@ async function scanGitHubRepo(repo, options) {
1032
1040
  let branch = repo.branch;
1033
1041
  if (!branch) {
1034
1042
  const repoResponse = await fetch(`https://api.github.com/repos/${repo.owner}/${repo.repo}`, { headers });
1035
- if (repoResponse.status === 404 && !options.githubToken) {
1036
- throw new Error("This appears to be a private repository. To scan private repos, add a GitHub personal access token in Flagrix settings.");
1043
+ if (repoResponse.status === 404) {
1044
+ throw githubNotFoundError(Boolean(options.githubToken));
1037
1045
  }
1038
1046
  if (!repoResponse.ok) {
1039
1047
  throw await githubApiError(repoResponse);
@@ -1042,8 +1050,8 @@ async function scanGitHubRepo(repo, options) {
1042
1050
  branch = repoData.default_branch || "main";
1043
1051
  }
1044
1052
  const commitResponse = await fetch(`https://api.github.com/repos/${repo.owner}/${repo.repo}/commits/${encodeURIComponent(branch)}`, { headers });
1045
- if (commitResponse.status === 404 && !options.githubToken) {
1046
- throw new Error("This appears to be a private repository. To scan private repos, add a GitHub personal access token in Flagrix settings.");
1053
+ if (commitResponse.status === 404) {
1054
+ throw githubNotFoundError(Boolean(options.githubToken));
1047
1055
  }
1048
1056
  if (!commitResponse.ok) {
1049
1057
  throw await githubApiError(commitResponse);
@@ -1051,8 +1059,8 @@ async function scanGitHubRepo(repo, options) {
1051
1059
  const commitSha = (await commitResponse.json()).sha;
1052
1060
  const treeUrl = `https://api.github.com/repos/${repo.owner}/${repo.repo}/git/trees/${commitSha}?recursive=1`;
1053
1061
  const treeResponse = await fetch(treeUrl, { headers });
1054
- if (treeResponse.status === 404 && !options.githubToken) {
1055
- throw new Error("This appears to be a private repository. To scan private repos, add a GitHub personal access token in Flagrix settings.");
1062
+ if (treeResponse.status === 404) {
1063
+ throw githubNotFoundError(Boolean(options.githubToken));
1056
1064
  }
1057
1065
  if (!treeResponse.ok) {
1058
1066
  throw await githubApiError(treeResponse);
@@ -1129,12 +1137,24 @@ async function scanGitHubRepo(repo, options) {
1129
1137
  const loadedRuleIds = new Set(yaraRules.map((r) => r.id));
1130
1138
  const fileContents = [];
1131
1139
  const scannedFiles = [];
1140
+ let rateLimited = false;
1141
+ let fetchFailures = 0;
1132
1142
  const declaredDependencies = [];
1133
1143
  const localPackageNames = /* @__PURE__ */ new Set();
1134
1144
  for (const file of filesToScan) {
1145
+ if (rateLimited) {
1146
+ skip(file.path, "rate-limited");
1147
+ continue;
1148
+ }
1135
1149
  const contentUrl = `https://api.github.com/repos/${repo.owner}/${repo.repo}/contents/${file.path}?ref=${commitSha}`;
1136
1150
  const contentResponse = await fetch(contentUrl, { headers });
1137
1151
  if (!contentResponse.ok) {
1152
+ if (isRateLimitResponse(contentResponse)) {
1153
+ rateLimited = true;
1154
+ skip(file.path, "rate-limited");
1155
+ continue;
1156
+ }
1157
+ fetchFailures++;
1138
1158
  skip(file.path, "fetch-failed");
1139
1159
  continue;
1140
1160
  }
@@ -1296,7 +1316,9 @@ async function scanGitHubRepo(repo, options) {
1296
1316
  scannedFiles,
1297
1317
  skippedFiles,
1298
1318
  skippedCount,
1299
- treeTruncated: tree.truncated
1319
+ treeTruncated: tree.truncated,
1320
+ complete: !rateLimited && fetchFailures === 0,
1321
+ ...rateLimited ? { incompleteReason: "rate-limit" } : fetchFailures > 0 ? { incompleteReason: "fetch-errors" } : {}
1300
1322
  },
1301
1323
  findings,
1302
1324
  safeToClone: cloneRiskLevel === "low",
@@ -2699,6 +2721,41 @@ async function loadOsvFeed() {
2699
2721
  return cachedFeed;
2700
2722
  }
2701
2723
 
2724
+ // src/lib/coverage.ts
2725
+ function coverageOf(result) {
2726
+ const summary = result.scanSummary;
2727
+ const complete = summary.complete !== false;
2728
+ const filesUnread = (summary.skippedFiles ?? []).filter(
2729
+ (file) => file.reason === "rate-limited" || file.reason === "fetch-failed"
2730
+ ).length;
2731
+ return {
2732
+ complete,
2733
+ unreliableClear: !complete && result.riskLevel === "low",
2734
+ filesRead: summary.filesScanned,
2735
+ filesUnread,
2736
+ reason: summary.incompleteReason
2737
+ };
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
+ }
2748
+ function describeCoverage(coverage) {
2749
+ if (coverage.complete) return "";
2750
+ const read = `${coverage.filesRead} ${coverage.filesRead === 1 ? "file" : "files"} read`;
2751
+ const counts = coverage.filesUnread > 0 ? `${read}, ${coverage.filesUnread} left unread` : read;
2752
+ const consequence = coverage.unreliableClear ? "Nothing was found in what was read \u2014 that is not the same as nothing being there." : "There may be more than what is reported here.";
2753
+ if (coverage.reason === "rate-limit") {
2754
+ return `Stopped early \u2014 GitHub rate limit: ${counts}. Unauthenticated scans share 60 API requests an hour and one scan can need up to 200, so the rest of the repository was never looked at. A token raises the limit to 5,000/hour (--token, or GITHUB_TOKEN / FLAGRIX_GITHUB_TOKEN). ${consequence}`;
2755
+ }
2756
+ return `Scan incomplete \u2014 some files could not be read: ${counts}. GitHub did not return the rest, so this rests on partial evidence; re-scanning usually clears it up. ${consequence}`;
2757
+ }
2758
+
2702
2759
  // src/lib/render.ts
2703
2760
  var useColor = process.stdout.isTTY && !process.env.NO_COLOR;
2704
2761
  var paint = (code) => (s) => useColor ? `\x1B[${code}m${s}\x1B[0m` : s;
@@ -2708,28 +2765,53 @@ var red = paint("31");
2708
2765
  var yellow = paint("33");
2709
2766
  var green = paint("32");
2710
2767
  var VERDICTS = {
2711
- low: { label: "LOW RISK", verdict: "Safe to clone", color: green },
2768
+ low: { label: "LOW RISK", verdict: "No blocking findings", color: green },
2712
2769
  medium: { label: "MEDIUM RISK", verdict: "Review before cloning", color: yellow },
2713
2770
  high: { label: "HIGH RISK", verdict: "Do not clone", color: red }
2714
2771
  };
2772
+ function wrapNote(text, indent, width = 78) {
2773
+ const lines = [];
2774
+ let line = "";
2775
+ for (const word of text.split(" ")) {
2776
+ if (line && (indent + line + " " + word).length > width) {
2777
+ lines.push(indent + line);
2778
+ line = word;
2779
+ } else {
2780
+ line = line ? `${line} ${word}` : word;
2781
+ }
2782
+ }
2783
+ if (line) lines.push(indent + line);
2784
+ return lines;
2785
+ }
2715
2786
  function securityScore(riskScore) {
2716
2787
  return 100 - Math.round(riskScore * 100);
2717
2788
  }
2718
2789
  function renderRepoResult(result) {
2719
2790
  const v = VERDICTS[result.riskLevel];
2791
+ const coverage = coverageOf(result);
2720
2792
  const slug = `${result.repo.owner}/${result.repo.repo}`;
2721
2793
  const sha = result.commitSha?.slice(0, 7);
2722
2794
  const lines = [];
2723
2795
  lines.push("");
2724
2796
  lines.push(` ${bold(slug)}${sha ? dim(` @ ${sha}`) : ""}`);
2725
- lines.push(
2726
- ` ${v.color(bold(`${v.label} \u2014 ${v.verdict}`))} ${dim(`security score ${securityScore(result.riskScore)}/100`)}`
2727
- );
2797
+ if (coverage.unreliableClear) {
2798
+ lines.push(
2799
+ ` ${yellow(bold("SCAN INCOMPLETE \u2014 no verdict"))} ${dim("not enough of this repository was read to give a verdict")}`
2800
+ );
2801
+ } else {
2802
+ lines.push(
2803
+ ` ${v.color(bold(`${v.label} \u2014 ${v.verdict}`))} ${dim(`security score ${securityScore(result.riskScore)}/100`)}`
2804
+ );
2805
+ }
2728
2806
  lines.push(
2729
2807
  dim(
2730
2808
  ` ${result.scanSummary.filesScanned} files scanned \xB7 ${result.scanSummary.dependenciesChecked} dependencies \xB7 ${result.findings.length} issue${result.findings.length === 1 ? "" : "s"}`
2731
2809
  )
2732
2810
  );
2811
+ if (!coverage.complete) {
2812
+ lines.push("");
2813
+ for (const line of wrapNote(describeCoverage(coverage), " ")) lines.push(yellow(line));
2814
+ }
2733
2815
  for (const f of result.findings) {
2734
2816
  lines.push("");
2735
2817
  lines.push(` ${bold(f.severity.toUpperCase())} ${f.description}`);
@@ -2776,10 +2858,13 @@ function renderUserResult(result) {
2776
2858
  }
2777
2859
 
2778
2860
  // src/commands/shared.ts
2779
- var EXIT = { LOW: 0, ERROR: 1, MEDIUM: 2, HIGH: 3 };
2861
+ var EXIT = { LOW: 0, ERROR: 1, MEDIUM: 2, HIGH: 3, INCOMPLETE: 4 };
2780
2862
  function exitCodeFor(level) {
2781
2863
  return level === "high" ? EXIT.HIGH : level === "medium" ? EXIT.MEDIUM : EXIT.LOW;
2782
2864
  }
2865
+ function exitCodeForScan(result) {
2866
+ return coverageOf(result).unreliableClear ? EXIT.INCOMPLETE : exitCodeFor(result.riskLevel);
2867
+ }
2783
2868
  function resolveToken(flag) {
2784
2869
  return flag || process.env.FLAGRIX_GITHUB_TOKEN || process.env.GITHUB_TOKEN || void 0;
2785
2870
  }
@@ -2794,11 +2879,15 @@ export {
2794
2879
  loadSignatures,
2795
2880
  describeSource,
2796
2881
  loadOsvFeed,
2882
+ coverageOf,
2883
+ scanReport,
2884
+ describeCoverage,
2797
2885
  securityScore,
2798
2886
  renderRepoResult,
2799
2887
  renderUserResult,
2800
2888
  EXIT,
2801
2889
  exitCodeFor,
2890
+ exitCodeForScan,
2802
2891
  resolveToken,
2803
2892
  wantJson
2804
2893
  };
package/dist/cli.js CHANGED
@@ -3,6 +3,7 @@ import {
3
3
  EXIT,
4
4
  describeSource,
5
5
  exitCodeFor,
6
+ exitCodeForScan,
6
7
  loadOsvFeed,
7
8
  loadSignatures,
8
9
  parseRepoTarget,
@@ -11,8 +12,9 @@ import {
11
12
  resolveToken,
12
13
  scanGitHubRepo,
13
14
  scanGitHubUser,
15
+ scanReport,
14
16
  wantJson
15
- } from "./chunk-34LISSSS.js";
17
+ } from "./chunk-B67OPHC4.js";
16
18
 
17
19
  // src/cli.ts
18
20
  import { parseArgs } from "util";
@@ -37,11 +39,11 @@ async function runScan(target, options) {
37
39
  };
38
40
  const result = await scanGitHubRepo(repo, scanOptions);
39
41
  if (wantJson(options.json)) {
40
- console.log(JSON.stringify(result, null, 2));
42
+ console.log(JSON.stringify(scanReport(result), null, 2));
41
43
  } else {
42
44
  console.log(renderRepoResult(result));
43
45
  }
44
- return exitCodeFor(result.riskLevel);
46
+ return exitCodeForScan(result);
45
47
  } catch (error) {
46
48
  console.error(`flagrix: scan failed \u2014 ${error.message}`);
47
49
  return EXIT.ERROR;
@@ -76,7 +78,7 @@ async function runScanUser(login, options) {
76
78
  }
77
79
 
78
80
  // src/cli.ts
79
- var VERSION = "0.1.0";
81
+ var VERSION = "0.5.0";
80
82
  var HELP = `flagrix \u2014 scan GitHub repos and profiles for malware before you clone
81
83
 
82
84
  Usage:
@@ -94,10 +96,15 @@ Options:
94
96
  Exit codes:
95
97
  0 low risk 2 medium risk \u2014 review before proceeding
96
98
  1 scan failed 3 high risk \u2014 do not clone
99
+ 4 scan incomplete \u2014 not enough of the repository was read to give a verdict
97
100
 
98
101
  The verdict is pinned to the scanned commit SHA (in the JSON output as
99
- "commitSha"). Scanning is fully local: the only network calls go to the
100
- GitHub/npm APIs and the public detection-rules repository. No telemetry.
102
+ "commitSha"). A scan that runs out of GitHub API budget reports partial
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.
101
108
  Docs: https://github.com/flagrix-io/flagrix-cli`;
102
109
  async function main() {
103
110
  const { values, positionals } = parseArgs({
@@ -135,7 +142,7 @@ async function main() {
135
142
  }
136
143
  return runScanUser(target, { json: values.json, token: values.token });
137
144
  case "mcp": {
138
- const { runMcp } = await import("./mcp-7CQFVW5O.js");
145
+ const { runMcp } = await import("./mcp-VIZ2IITR.js");
139
146
  return runMcp();
140
147
  }
141
148
  default:
@@ -1,5 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import {
3
+ coverageOf,
4
+ describeCoverage,
3
5
  describeSource,
4
6
  loadOsvFeed,
5
7
  loadSignatures,
@@ -7,8 +9,9 @@ import {
7
9
  resolveToken,
8
10
  scanGitHubRepo,
9
11
  scanGitHubUser,
12
+ scanReport,
10
13
  securityScore
11
- } from "./chunk-34LISSSS.js";
14
+ } from "./chunk-B67OPHC4.js";
12
15
 
13
16
  // src/commands/mcp.ts
14
17
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -19,8 +22,27 @@ var GUIDANCE = {
19
22
  medium: "MEDIUM risk: do NOT clone, install, or execute this code until a human has reviewed the findings.",
20
23
  high: "HIGH risk: do NOT clone, install, or execute this code. Treat the repository as malicious."
21
24
  };
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.";
26
+ function repoScanResponse(result, note) {
27
+ const coverage = coverageOf(result);
28
+ const pinned = `(verdict pinned to commit ${result.commitSha ?? "unknown"})`;
29
+ const headline = coverage.unreliableClear ? `INCOMPLETE SCAN \u2014 no verdict, security score withheld ${pinned}.` : `${result.riskLevel.toUpperCase()} risk \u2014 security score ${securityScore(result.riskScore)}/100 ${pinned}.`;
30
+ const summary = [
31
+ headline,
32
+ coverage.unreliableClear ? INCOMPLETE_GUIDANCE : GUIDANCE[result.riskLevel],
33
+ ...coverage.complete ? [] : [describeCoverage(coverage)],
34
+ ...note ? [`Note: ${note}.`] : []
35
+ ].join(" ");
36
+ return {
37
+ content: [
38
+ { type: "text", text: summary },
39
+ { type: "text", text: JSON.stringify(scanReport(result), null, 2) }
40
+ ],
41
+ isError: false
42
+ };
43
+ }
22
44
  async function runMcp() {
23
- const server = new McpServer({ name: "flagrix", version: "0.1.0" });
45
+ const server = new McpServer({ name: "flagrix", version: "0.5.0" });
24
46
  server.registerTool(
25
47
  "scan_github_repo",
26
48
  {
@@ -40,19 +62,7 @@ async function runMcp() {
40
62
  osvFeed: await loadOsvFeed()
41
63
  };
42
64
  const result = await scanGitHubRepo(repo, scanOptions);
43
- const note = describeSource(loaded);
44
- const summary = [
45
- `${result.riskLevel.toUpperCase()} risk \u2014 security score ${securityScore(result.riskScore)}/100 (verdict pinned to commit ${result.commitSha ?? "unknown"}).`,
46
- GUIDANCE[result.riskLevel],
47
- ...note ? [`Note: ${note}.`] : []
48
- ].join(" ");
49
- return {
50
- content: [
51
- { type: "text", text: summary },
52
- { type: "text", text: JSON.stringify(result, null, 2) }
53
- ],
54
- isError: false
55
- };
65
+ return repoScanResponse(result, describeSource(loaded));
56
66
  }
57
67
  );
58
68
  server.registerTool(
@@ -87,5 +97,6 @@ async function runMcp() {
87
97
  return 0;
88
98
  }
89
99
  export {
100
+ repoScanResponse,
90
101
  runMcp
91
102
  };
@@ -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
@@ -68,4 +82,6 @@ your repo and point the hook at it. The hook only reacts to `git clone` /
68
82
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
69
83
  ```
70
84
 
71
- A non-zero exit fails the job (2/3 = risk verdicts, 1 = scan error).
85
+ A non-zero exit fails the job (2/3 = risk verdicts, 1 = scan error, 4 = the
86
+ scan read too little of the repository to give a verdict — commonly GitHub's
87
+ 60 req/h limit, which `GITHUB_TOKEN` above raises to 5,000/h).
@@ -2,8 +2,9 @@
2
2
  # Flagrix clone gate — Claude Code PreToolUse hook for the Bash tool.
3
3
  #
4
4
  # Scans any GitHub repo about to be cloned; blocks the clone (hook exit 2)
5
- # when Flagrix rates it MEDIUM or HIGH risk. See docs/agent-gating.md for the
6
- # settings.json wiring.
5
+ # when Flagrix rates it MEDIUM or HIGH risk, or when the scan could not read
6
+ # enough of the repository to give a verdict (exit 4). See docs/agent-gating.md
7
+ # for the settings.json wiring.
7
8
  set -euo pipefail
8
9
 
9
10
  payload="$(cat)"
@@ -35,6 +36,7 @@ else
35
36
  case "$code" in
36
37
  2) echo "Flagrix: MEDIUM risk — review https://github.com/flagrix-io/flagrix-cli#exit-codes before cloning $url" >&2 ;;
37
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 — not enough was read to give a verdict (usually GitHub's 60 req/h limit; set GITHUB_TOKEN). Run: npx flagrix scan $url" >&2 ;;
38
40
  *) echo "Flagrix: scan of $url failed (exit $code) — blocking out of caution. Run: npx flagrix scan $url" >&2 ;;
39
41
  esac
40
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.3.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",
@@ -53,7 +53,7 @@
53
53
  "zod": "^3.24.0"
54
54
  },
55
55
  "devDependencies": {
56
- "@flagrix/scanner-core": "^0.5.0",
56
+ "@flagrix/scanner-core": "^0.6.0",
57
57
  "@types/node": "^20.0.0",
58
58
  "tsup": "^8.0.0",
59
59
  "typescript": "^5.0.0",