flagrix 0.3.0 → 0.4.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,31 @@ 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
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
+ Set a token to make this rare: `GITHUB_TOKEN` raises the budget to 5,000/h.
64
+
45
65
  ## AI agents
46
66
 
47
67
  ```bash
@@ -55,8 +75,10 @@ Tools: `scan_github_repo`, `scan_github_user`. A Claude Code hook that gates eve
55
75
  ## Tokens & rate limits
56
76
 
57
77
  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.
78
+ scanned file, up to ~200). Set `GITHUB_TOKEN` (or `FLAGRIX_GITHUB_TOKEN`, or
79
+ `--token`) to raise it to 5,000/h and to scan private repositories. A scan that
80
+ runs out of budget reports partial coverage and exits 4 — see
81
+ [Incomplete scans](#incomplete-scans-exit-4).
60
82
 
61
83
  ## Privacy
62
84
 
@@ -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,32 @@ 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 describeCoverage(coverage) {
2740
+ if (coverage.complete) return "";
2741
+ const read = `${coverage.filesRead} ${coverage.filesRead === 1 ? "file" : "files"} read`;
2742
+ const counts = coverage.filesUnread > 0 ? `${read}, ${coverage.filesUnread} left unread` : read;
2743
+ 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.";
2744
+ if (coverage.reason === "rate-limit") {
2745
+ 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}`;
2746
+ }
2747
+ 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}`;
2748
+ }
2749
+
2702
2750
  // src/lib/render.ts
2703
2751
  var useColor = process.stdout.isTTY && !process.env.NO_COLOR;
2704
2752
  var paint = (code) => (s) => useColor ? `\x1B[${code}m${s}\x1B[0m` : s;
@@ -2712,24 +2760,49 @@ var VERDICTS = {
2712
2760
  medium: { label: "MEDIUM RISK", verdict: "Review before cloning", color: yellow },
2713
2761
  high: { label: "HIGH RISK", verdict: "Do not clone", color: red }
2714
2762
  };
2763
+ function wrapNote(text, indent, width = 78) {
2764
+ const lines = [];
2765
+ let line = "";
2766
+ for (const word of text.split(" ")) {
2767
+ if (line && (indent + line + " " + word).length > width) {
2768
+ lines.push(indent + line);
2769
+ line = word;
2770
+ } else {
2771
+ line = line ? `${line} ${word}` : word;
2772
+ }
2773
+ }
2774
+ if (line) lines.push(indent + line);
2775
+ return lines;
2776
+ }
2715
2777
  function securityScore(riskScore) {
2716
2778
  return 100 - Math.round(riskScore * 100);
2717
2779
  }
2718
2780
  function renderRepoResult(result) {
2719
2781
  const v = VERDICTS[result.riskLevel];
2782
+ const coverage = coverageOf(result);
2720
2783
  const slug = `${result.repo.owner}/${result.repo.repo}`;
2721
2784
  const sha = result.commitSha?.slice(0, 7);
2722
2785
  const lines = [];
2723
2786
  lines.push("");
2724
2787
  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
- );
2788
+ if (coverage.unreliableClear) {
2789
+ lines.push(
2790
+ ` ${yellow(bold("SCAN INCOMPLETE \u2014 no verdict"))} ${dim("too little of this repository was read to call it safe")}`
2791
+ );
2792
+ } else {
2793
+ lines.push(
2794
+ ` ${v.color(bold(`${v.label} \u2014 ${v.verdict}`))} ${dim(`security score ${securityScore(result.riskScore)}/100`)}`
2795
+ );
2796
+ }
2728
2797
  lines.push(
2729
2798
  dim(
2730
2799
  ` ${result.scanSummary.filesScanned} files scanned \xB7 ${result.scanSummary.dependenciesChecked} dependencies \xB7 ${result.findings.length} issue${result.findings.length === 1 ? "" : "s"}`
2731
2800
  )
2732
2801
  );
2802
+ if (!coverage.complete) {
2803
+ lines.push("");
2804
+ for (const line of wrapNote(describeCoverage(coverage), " ")) lines.push(yellow(line));
2805
+ }
2733
2806
  for (const f of result.findings) {
2734
2807
  lines.push("");
2735
2808
  lines.push(` ${bold(f.severity.toUpperCase())} ${f.description}`);
@@ -2776,10 +2849,13 @@ function renderUserResult(result) {
2776
2849
  }
2777
2850
 
2778
2851
  // src/commands/shared.ts
2779
- var EXIT = { LOW: 0, ERROR: 1, MEDIUM: 2, HIGH: 3 };
2852
+ var EXIT = { LOW: 0, ERROR: 1, MEDIUM: 2, HIGH: 3, INCOMPLETE: 4 };
2780
2853
  function exitCodeFor(level) {
2781
2854
  return level === "high" ? EXIT.HIGH : level === "medium" ? EXIT.MEDIUM : EXIT.LOW;
2782
2855
  }
2856
+ function exitCodeForScan(result) {
2857
+ return coverageOf(result).unreliableClear ? EXIT.INCOMPLETE : exitCodeFor(result.riskLevel);
2858
+ }
2783
2859
  function resolveToken(flag) {
2784
2860
  return flag || process.env.FLAGRIX_GITHUB_TOKEN || process.env.GITHUB_TOKEN || void 0;
2785
2861
  }
@@ -2794,11 +2870,14 @@ export {
2794
2870
  loadSignatures,
2795
2871
  describeSource,
2796
2872
  loadOsvFeed,
2873
+ coverageOf,
2874
+ describeCoverage,
2797
2875
  securityScore,
2798
2876
  renderRepoResult,
2799
2877
  renderUserResult,
2800
2878
  EXIT,
2801
2879
  exitCodeFor,
2880
+ exitCodeForScan,
2802
2881
  resolveToken,
2803
2882
  wantJson
2804
2883
  };
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,
@@ -12,7 +13,7 @@ import {
12
13
  scanGitHubRepo,
13
14
  scanGitHubUser,
14
15
  wantJson
15
- } from "./chunk-34LISSSS.js";
16
+ } from "./chunk-XBQCLZNK.js";
16
17
 
17
18
  // src/cli.ts
18
19
  import { parseArgs } from "util";
@@ -41,7 +42,7 @@ async function runScan(target, options) {
41
42
  } else {
42
43
  console.log(renderRepoResult(result));
43
44
  }
44
- return exitCodeFor(result.riskLevel);
45
+ return exitCodeForScan(result);
45
46
  } catch (error) {
46
47
  console.error(`flagrix: scan failed \u2014 ${error.message}`);
47
48
  return EXIT.ERROR;
@@ -76,7 +77,7 @@ async function runScanUser(login, options) {
76
77
  }
77
78
 
78
79
  // src/cli.ts
79
- var VERSION = "0.1.0";
80
+ var VERSION = "0.4.0";
80
81
  var HELP = `flagrix \u2014 scan GitHub repos and profiles for malware before you clone
81
82
 
82
83
  Usage:
@@ -94,10 +95,15 @@ Options:
94
95
  Exit codes:
95
96
  0 low risk 2 medium risk \u2014 review before proceeding
96
97
  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
97
99
 
98
100
  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.
101
+ "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.
101
107
  Docs: https://github.com/flagrix-io/flagrix-cli`;
102
108
  async function main() {
103
109
  const { values, positionals } = parseArgs({
@@ -135,7 +141,7 @@ async function main() {
135
141
  }
136
142
  return runScanUser(target, { json: values.json, token: values.token });
137
143
  case "mcp": {
138
- const { runMcp } = await import("./mcp-7CQFVW5O.js");
144
+ const { runMcp } = await import("./mcp-EHS7B5VR.js");
139
145
  return runMcp();
140
146
  }
141
147
  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,
@@ -8,7 +10,7 @@ import {
8
10
  scanGitHubRepo,
9
11
  scanGitHubUser,
10
12
  securityScore
11
- } from "./chunk-34LISSSS.js";
13
+ } from "./chunk-XBQCLZNK.js";
12
14
 
13
15
  // src/commands/mcp.ts
14
16
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -19,8 +21,27 @@ var GUIDANCE = {
19
21
  medium: "MEDIUM risk: do NOT clone, install, or execute this code until a human has reviewed the findings.",
20
22
  high: "HIGH risk: do NOT clone, install, or execute this code. Treat the repository as malicious."
21
23
  };
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
+ function repoScanResponse(result, note) {
26
+ const coverage = coverageOf(result);
27
+ const pinned = `(verdict pinned to commit ${result.commitSha ?? "unknown"})`;
28
+ 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}.`;
29
+ const summary = [
30
+ headline,
31
+ coverage.unreliableClear ? INCOMPLETE_GUIDANCE : GUIDANCE[result.riskLevel],
32
+ ...coverage.complete ? [] : [describeCoverage(coverage)],
33
+ ...note ? [`Note: ${note}.`] : []
34
+ ].join(" ");
35
+ return {
36
+ content: [
37
+ { type: "text", text: summary },
38
+ { type: "text", text: JSON.stringify(result, null, 2) }
39
+ ],
40
+ isError: false
41
+ };
42
+ }
22
43
  async function runMcp() {
23
- const server = new McpServer({ name: "flagrix", version: "0.1.0" });
44
+ const server = new McpServer({ name: "flagrix", version: "0.4.0" });
24
45
  server.registerTool(
25
46
  "scan_github_repo",
26
47
  {
@@ -40,19 +61,7 @@ async function runMcp() {
40
61
  osvFeed: await loadOsvFeed()
41
62
  };
42
63
  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
- };
64
+ return repoScanResponse(result, describeSource(loaded));
56
65
  }
57
66
  );
58
67
  server.registerTool(
@@ -87,5 +96,6 @@ async function runMcp() {
87
96
  return 0;
88
97
  }
89
98
  export {
99
+ repoScanResponse,
90
100
  runMcp
91
101
  };
@@ -68,4 +68,6 @@ your repo and point the hook at it. The hook only reacts to `git clone` /
68
68
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
69
69
  ```
70
70
 
71
- A non-zero exit fails the job (2/3 = risk verdicts, 1 = scan error).
71
+ 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
73
+ 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 call it safe (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 — 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 ;;
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.4.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",