flagrix 0.2.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
 
@@ -65,6 +87,13 @@ calls go to the GitHub/npm APIs and the public
65
87
  [detection-rules](https://github.com/flagrix-io/flagrix-detection-rules)
66
88
  repository (signature refresh, cached 6 h, with a bundled offline snapshot).
67
89
 
90
+ Dependencies are also checked against the OSV malicious-package feed
91
+ (`osv-malicious.json` from the same repository: every npm/PyPI package the
92
+ OpenSSF malicious-packages project has confirmed malicious). The feed is
93
+ downloaded and matched locally, so dependency names never leave your machine.
94
+ It is cached 6 h and revalidated with its ETag. Set `FLAGRIX_OSV_FEED=0` to
95
+ skip it (the curated list in the signatures still applies).
96
+
68
97
  ## How it works
69
98
 
70
99
  Scanning logic lives in [@flagrix/scanner-core](https://github.com/flagrix-io/flagrix-scanner-core)
@@ -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 {
@@ -519,6 +527,211 @@ async function githubApiError(response, fallback = "GitHub API error") {
519
527
  return new Error(apiMessage ? `${fallback}: ${response.status} \u2014 ${apiMessage}` : `${fallback}: ${response.status}`);
520
528
  }
521
529
 
530
+ // node_modules/@flagrix/scanner-core/dist/github/history-signals.js
531
+ var BACKDATED_PUSH_DAYS = 30;
532
+ var RECENT_FORCE_PUSH_DAYS = 90;
533
+ var DAY_MS = 24 * 60 * 60 * 1e3;
534
+ var NULL_SHA = /^0+$/;
535
+ function detectHistoryTampering(activity, commits, branch, now = Date.now()) {
536
+ const ref = `refs/heads/${branch}`;
537
+ const onBranch = activity.filter((event) => event.ref === ref);
538
+ const commitsBySha = new Map(commits.map((commit) => [commit.sha, commit]));
539
+ let worst = null;
540
+ for (const event of onBranch) {
541
+ if (event.activity_type !== "push" && event.activity_type !== "force_push")
542
+ continue;
543
+ if (!event.before || NULL_SHA.test(event.before))
544
+ continue;
545
+ const commit = commitsBySha.get(event.after);
546
+ if (!commit || commit.commit.verification?.verified)
547
+ continue;
548
+ const committed = commit.commit.committer?.date;
549
+ if (!committed)
550
+ continue;
551
+ const committedAt = new Date(committed);
552
+ const lagDays = Math.floor((Date.parse(event.timestamp) - committedAt.getTime()) / DAY_MS);
553
+ if (lagDays >= BACKDATED_PUSH_DAYS && (!worst || lagDays > worst.lagDays)) {
554
+ worst = { event, committedAt, lagDays };
555
+ }
556
+ }
557
+ if (worst) {
558
+ const force = worst.event.activity_type === "force_push";
559
+ const sha = worst.event.after.slice(0, 7);
560
+ return [{
561
+ severity: force ? "high" : "medium",
562
+ confidence: "medium",
563
+ type: "GIT_HISTORY_TAMPERING",
564
+ pattern: "BACKDATED_PUSH",
565
+ description: `Unsigned commit ${sha} on ${branch} is dated ${worst.committedAt.toISOString().slice(0, 10)} but was ${force ? "force-pushed" : "pushed"} ${worst.lagDays} days later (${worst.event.timestamp.slice(0, 10)})`,
566
+ codeExplanation: "\u{1F570}\uFE0F The commit's date says it is old, but GitHub only received it recently. Account-takeover campaigns (PolinRider) backdate commits and force-push them so new loader code looks like long-standing history. Check what this commit changed before cloning."
567
+ }];
568
+ }
569
+ const forcePushes = onBranch.filter((event) => event.activity_type === "force_push" && now - Date.parse(event.timestamp) < RECENT_FORCE_PUSH_DAYS * DAY_MS);
570
+ if (forcePushes.length > 0) {
571
+ const latest = forcePushes[0];
572
+ return [{
573
+ severity: "low",
574
+ confidence: "low",
575
+ cloneBlocking: false,
576
+ type: "GIT_HISTORY_TAMPERING",
577
+ pattern: "FORCE_PUSH",
578
+ description: `${branch} history was rewritten by a force push on ${latest.timestamp.slice(0, 10)}` + (forcePushes.length > 1 ? ` (${forcePushes.length} force pushes in the last ${RECENT_FORCE_PUSH_DAYS} days)` : ""),
579
+ codeExplanation: "Force pushes are common in personal repositories, but they also hide which code is new. Compare the current code with what you expected before running it."
580
+ }];
581
+ }
582
+ return [];
583
+ }
584
+ async function fetchHistorySignals(repoPath, branch, commitSha, headers) {
585
+ try {
586
+ const ref = encodeURIComponent(`refs/heads/${branch}`);
587
+ const [activityResponse, commitsResponse] = await Promise.all([
588
+ fetch(`https://api.github.com/repos/${repoPath}/activity?ref=${ref}&per_page=100`, { headers }),
589
+ fetch(`https://api.github.com/repos/${repoPath}/commits?sha=${commitSha}&per_page=100`, { headers })
590
+ ]);
591
+ if (!activityResponse.ok || !commitsResponse.ok)
592
+ return [];
593
+ const activity = await activityResponse.json();
594
+ const commits = await commitsResponse.json();
595
+ if (!Array.isArray(activity) || !Array.isArray(commits))
596
+ return [];
597
+ return detectHistoryTampering(activity, commits, branch);
598
+ } catch {
599
+ return [];
600
+ }
601
+ }
602
+
603
+ // node_modules/@flagrix/scanner-core/dist/github/osv-feed.js
604
+ var INDEXES = /* @__PURE__ */ new WeakMap();
605
+ function indexFeed(feed) {
606
+ let index = INDEXES.get(feed);
607
+ if (!index) {
608
+ const build = (ecosystem) => ({
609
+ all: new Set(ecosystem?.all ?? []),
610
+ versions: new Map(Object.entries(ecosystem?.versions ?? {}))
611
+ });
612
+ index = { npm: build(feed.npm), pypi: build(feed.pypi) };
613
+ INDEXES.set(feed, index);
614
+ }
615
+ return index;
616
+ }
617
+ function normalizePypiName(name) {
618
+ return name.toLowerCase().replace(/[-_.]+/g, "-");
619
+ }
620
+ var LOCAL_OR_URL_SPEC = /^(?:workspace:|file:|link:|portal:|git\+|git:|github:|gitlab:|bitbucket:|https?:)/;
621
+ function compareVersions(a, b) {
622
+ const [mainA = "", preA] = a.split("-", 2);
623
+ const [mainB = "", preB] = b.split("-", 2);
624
+ const partsA = mainA.split(".");
625
+ const partsB = mainB.split(".");
626
+ for (let index = 0; index < Math.max(partsA.length, partsB.length); index++) {
627
+ const diff = (Number.parseInt(partsA[index] ?? "0", 10) || 0) - (Number.parseInt(partsB[index] ?? "0", 10) || 0);
628
+ if (diff !== 0)
629
+ return Math.sign(diff);
630
+ }
631
+ if (preA === preB)
632
+ return 0;
633
+ if (preA === void 0)
634
+ return 1;
635
+ if (preB === void 0)
636
+ return -1;
637
+ return preA < preB ? -1 : 1;
638
+ }
639
+ var VERSION_TOKEN = /\d+(?:\.\d+){0,3}(?:-[0-9A-Za-z.]+)?/;
640
+ var RANGE_PART = /(>=|<=|<|>)\s*(\S+)/g;
641
+ function inAffected(version, entry) {
642
+ if (!/[<>]/.test(entry))
643
+ return compareVersions(version, entry) === 0;
644
+ for (const [, operator, bound] of entry.matchAll(RANGE_PART)) {
645
+ const order = compareVersions(version, bound);
646
+ if (operator === ">=" && order < 0 || operator === ">" && order <= 0 || operator === "<=" && order > 0 || operator === "<" && order >= 0) {
647
+ return false;
648
+ }
649
+ }
650
+ return true;
651
+ }
652
+ function declaredMatch(spec, affected) {
653
+ let specifier = spec.trim();
654
+ const alias = specifier.match(/^npm:.+@([^@]+)$/);
655
+ if (alias)
656
+ specifier = alias[1];
657
+ let result = null;
658
+ for (const part of specifier.split(/\s*\|\|\s*/)) {
659
+ const base = part.match(VERSION_TOKEN)?.[0];
660
+ if (!base || !affected.some((entry) => inAffected(base, entry)))
661
+ continue;
662
+ if (/^\s*(?:={1,3}|v)?\s*\d/.test(part) && !/[\s,]/.test(part.trim().replace(/^={1,3}\s*/, "")))
663
+ return "exact";
664
+ result = "range";
665
+ }
666
+ return result;
667
+ }
668
+ function matchOsvFeed(feed, dependencies, localPackageNames, alreadyFlagged) {
669
+ const index = indexFeed(feed);
670
+ const findings = [];
671
+ const reported = /* @__PURE__ */ new Set();
672
+ for (const dependency of dependencies) {
673
+ const { ecosystem, name, spec, file } = dependency;
674
+ const key = `${ecosystem}:${name}`;
675
+ if (reported.has(key) || alreadyFlagged.has(name) || localPackageNames.has(name))
676
+ continue;
677
+ if (ecosystem === "npm" && LOCAL_OR_URL_SPEC.test(spec.trim()))
678
+ continue;
679
+ const ecosystemIndex = index[ecosystem];
680
+ const lookup = ecosystem === "pypi" ? normalizePypiName(name) : name;
681
+ const everyVersion = ecosystemIndex.all.has(lookup);
682
+ const affected = ecosystemIndex.versions.get(lookup);
683
+ const match = everyVersion ? "exact" : affected ? declaredMatch(spec, affected) : null;
684
+ if (!match)
685
+ continue;
686
+ reported.add(key);
687
+ const registry = ecosystem === "npm" ? "npm" : "PyPI";
688
+ findings.push({
689
+ severity: "critical",
690
+ // A caret/tilde/>= range may resolve past the malicious versions.
691
+ confidence: match === "exact" ? "high" : "medium",
692
+ type: "SUSPICIOUS_DEPENDENCY",
693
+ pattern: "OSV_MALICIOUS_PACKAGE",
694
+ file,
695
+ package: name,
696
+ description: `Confirmed malicious ${registry} package (OSV): ${name}`,
697
+ codeExplanation: `\u2620\uFE0F The OpenSSF malicious-packages project lists "${name}" as malicious` + (everyVersion ? "" : ` in the version this repo declares (${spec.trim()})`) + `. Installing it runs the attacker's code. Details: https://osv.dev/list?ecosystem=${registry}&q=${encodeURIComponent(name)}`
698
+ });
699
+ }
700
+ return findings;
701
+ }
702
+ function npmDependencies(pkg, file) {
703
+ const out = [];
704
+ for (const section of ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]) {
705
+ const deps = pkg[section];
706
+ if (!deps || typeof deps !== "object")
707
+ continue;
708
+ for (const [name, spec] of Object.entries(deps)) {
709
+ out.push({ ecosystem: "npm", name, spec: typeof spec === "string" ? spec : "", file });
710
+ }
711
+ }
712
+ return out;
713
+ }
714
+ var REQUIREMENT = /^\s*([A-Za-z0-9][A-Za-z0-9._-]*)\s*(?:\[[^\]]*\])?\s*([^;#]*)/;
715
+ function pythonDependencies(content, file) {
716
+ let lines;
717
+ if (file.endsWith("setup.py")) {
718
+ const block = content.match(/install_requires\s*=\s*\[([^\]]{0,20000})\]/);
719
+ lines = block ? [...block[1].matchAll(/["']([^"'\n]+)["']/g)].map((m) => m[1]) : [];
720
+ } else {
721
+ lines = content.split("\n");
722
+ }
723
+ const out = [];
724
+ for (const line of lines) {
725
+ const trimmed = line.trim();
726
+ if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("-") || trimmed.includes("://"))
727
+ continue;
728
+ const match = trimmed.match(REQUIREMENT);
729
+ if (match)
730
+ out.push({ ecosystem: "pypi", name: match[1], spec: match[2].trim(), file });
731
+ }
732
+ return out;
733
+ }
734
+
522
735
  // node_modules/@flagrix/scanner-core/dist/utils/risk-calculator.js
523
736
  function getSeverityWeight(severity) {
524
737
  const weights = {
@@ -749,6 +962,50 @@ function isFontFile(path) {
749
962
  return FONT_EXTENSIONS.some((ext) => path.toLowerCase().endsWith(ext));
750
963
  }
751
964
  var MAX_CONFIG_FILES = 25;
965
+ var MAX_COMMAND_TARGETS = 10;
966
+ var CI_WORKFLOW = /^\.github\/workflows\//;
967
+ var RUNTIME_INVOCATION = /\b(?:node|nodejs|bun|deno\s+run|tsx|ts-node)((?:\s+-{1,2}[\w-]+(?:=[^\s"'`]*)?)*)\s+\\?["']?([^\s"'`&|;<>()]+)/g;
968
+ var INLINE_CODE_FLAG = /(?:^|\s)(?:-[ep]|--eval|--print)(?:\s|=|$)/;
969
+ var RUNTIME_ARGS_FORM = /"command"\s*:\s*"(?:node|nodejs|bun|deno|tsx|ts-node)"\s*,\s*"args"\s*:\s*\[\s*"([^"]+)"/g;
970
+ var PROJECT_DIR_VARIABLE = /\\?["']?\$\{?(?:CLAUDE_PROJECT_DIR|workspaceFolder|workspaceRoot)\}?\\?["']?(?=\/)/g;
971
+ var DOT_DIR_CONFIG = /^(?:(.*)\/)?\.(?:vscode|claude|cursor|amazonq|gemini|windsurf|roo|kiro|github)\//;
972
+ function extractCommandTargets(content, configPath) {
973
+ const dotDir = configPath.match(DOT_DIR_CONFIG);
974
+ const base = dotDir ? dotDir[1] ?? "" : configPath.includes("/") ? configPath.slice(0, configPath.lastIndexOf("/")) : "";
975
+ const text = content.replace(PROJECT_DIR_VARIABLE, ".");
976
+ const targets = /* @__PURE__ */ new Set();
977
+ for (const match of text.matchAll(RUNTIME_INVOCATION)) {
978
+ if (INLINE_CODE_FLAG.test(match[1]))
979
+ continue;
980
+ const path = resolveRepoPath(base, match[2]);
981
+ if (path)
982
+ targets.add(path);
983
+ }
984
+ for (const match of text.matchAll(RUNTIME_ARGS_FORM)) {
985
+ const path = resolveRepoPath(base, match[1]);
986
+ if (path)
987
+ targets.add(path);
988
+ }
989
+ return [...targets];
990
+ }
991
+ function resolveRepoPath(base, raw) {
992
+ const target = raw.replace(/\\+$/, "");
993
+ if (!target || /^[-/~$]/.test(target) || target.includes("://"))
994
+ return null;
995
+ const segments = base ? base.split("/") : [];
996
+ for (const segment of target.split("/")) {
997
+ if (segment === "" || segment === ".")
998
+ continue;
999
+ if (segment === "..") {
1000
+ if (segments.length === 0)
1001
+ return null;
1002
+ segments.pop();
1003
+ } else {
1004
+ segments.push(segment);
1005
+ }
1006
+ }
1007
+ return segments.length > 0 ? segments.join("/") : null;
1008
+ }
752
1009
  var MAX_FILES_TO_SCAN = 200;
753
1010
  var MAX_FILE_SIZE_BYTES = 1024 * 1024;
754
1011
  var MAX_SKIPPED_FILES_LISTED = 500;
@@ -783,8 +1040,8 @@ async function scanGitHubRepo(repo, options) {
783
1040
  let branch = repo.branch;
784
1041
  if (!branch) {
785
1042
  const repoResponse = await fetch(`https://api.github.com/repos/${repo.owner}/${repo.repo}`, { headers });
786
- if (repoResponse.status === 404 && !options.githubToken) {
787
- 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));
788
1045
  }
789
1046
  if (!repoResponse.ok) {
790
1047
  throw await githubApiError(repoResponse);
@@ -793,8 +1050,8 @@ async function scanGitHubRepo(repo, options) {
793
1050
  branch = repoData.default_branch || "main";
794
1051
  }
795
1052
  const commitResponse = await fetch(`https://api.github.com/repos/${repo.owner}/${repo.repo}/commits/${encodeURIComponent(branch)}`, { headers });
796
- if (commitResponse.status === 404 && !options.githubToken) {
797
- 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));
798
1055
  }
799
1056
  if (!commitResponse.ok) {
800
1057
  throw await githubApiError(commitResponse);
@@ -802,8 +1059,8 @@ async function scanGitHubRepo(repo, options) {
802
1059
  const commitSha = (await commitResponse.json()).sha;
803
1060
  const treeUrl = `https://api.github.com/repos/${repo.owner}/${repo.repo}/git/trees/${commitSha}?recursive=1`;
804
1061
  const treeResponse = await fetch(treeUrl, { headers });
805
- if (treeResponse.status === 404 && !options.githubToken) {
806
- 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));
807
1064
  }
808
1065
  if (!treeResponse.ok) {
809
1066
  throw await githubApiError(treeResponse);
@@ -853,6 +1110,15 @@ async function scanGitHubRepo(repo, options) {
853
1110
  }
854
1111
  }
855
1112
  const filesToScan = [...extraFiles, ...sourceBlobs];
1113
+ const blobsByPath = new Map(tree.tree.filter((item) => item.type === "blob").map((item) => [item.path, item]));
1114
+ const queued = new Set(filesToScan.map((item) => item.path));
1115
+ const commandTargets = /* @__PURE__ */ new Set();
1116
+ const unskip = (path) => {
1117
+ const index = skippedFiles.findIndex((skipped) => skipped.path === path);
1118
+ if (index !== -1)
1119
+ skippedFiles.splice(index, 1);
1120
+ skippedCount--;
1121
+ };
856
1122
  const hiddenFiles = tree.tree.filter((item) => item.path.startsWith(".") && !item.path.startsWith(".github") && !item.path.startsWith(".git") && item.type === "blob");
857
1123
  for (const hidden of hiddenFiles) {
858
1124
  const basename = hidden.path.split("/").pop() ?? hidden.path;
@@ -871,10 +1137,24 @@ async function scanGitHubRepo(repo, options) {
871
1137
  const loadedRuleIds = new Set(yaraRules.map((r) => r.id));
872
1138
  const fileContents = [];
873
1139
  const scannedFiles = [];
1140
+ let rateLimited = false;
1141
+ let fetchFailures = 0;
1142
+ const declaredDependencies = [];
1143
+ const localPackageNames = /* @__PURE__ */ new Set();
874
1144
  for (const file of filesToScan) {
1145
+ if (rateLimited) {
1146
+ skip(file.path, "rate-limited");
1147
+ continue;
1148
+ }
875
1149
  const contentUrl = `https://api.github.com/repos/${repo.owner}/${repo.repo}/contents/${file.path}?ref=${commitSha}`;
876
1150
  const contentResponse = await fetch(contentUrl, { headers });
877
1151
  if (!contentResponse.ok) {
1152
+ if (isRateLimitResponse(contentResponse)) {
1153
+ rateLimited = true;
1154
+ skip(file.path, "rate-limited");
1155
+ continue;
1156
+ }
1157
+ fetchFailures++;
878
1158
  skip(file.path, "fetch-failed");
879
1159
  continue;
880
1160
  }
@@ -883,17 +1163,41 @@ async function scanGitHubRepo(repo, options) {
883
1163
  const fileData = await contentResponse.json();
884
1164
  const binary = atob(fileData.content || "");
885
1165
  const content = isFontFile(file.path) ? binary : decodeUtf8(binary);
1166
+ if (isConfigFile(file.path) && !CI_WORKFLOW.test(file.path) || file.path.endsWith("package.json")) {
1167
+ for (const target of extractCommandTargets(content, file.path)) {
1168
+ if (commandTargets.size >= MAX_COMMAND_TARGETS)
1169
+ break;
1170
+ const item = blobsByPath.get(target);
1171
+ if (!item || queued.has(target))
1172
+ continue;
1173
+ if (item.size !== void 0 && item.size > MAX_FILE_SIZE_BYTES)
1174
+ continue;
1175
+ unskip(target);
1176
+ queued.add(target);
1177
+ commandTargets.add(target);
1178
+ filesToScan.push(item);
1179
+ }
1180
+ }
1181
+ const isSource = SCANNABLE_EXTENSIONS.some((ext) => file.path.endsWith(ext));
1182
+ const runsAsJs = commandTargets.has(file.path) && !isSource && !isFontFile(file.path);
886
1183
  const isHtml = /\.html?$/i.test(file.path);
887
- const isJsTs = /\.(?:[cm]?js|ts|[jt]sx)$/i.test(file.path);
1184
+ const isJsTs = runsAsJs || /\.(?:[cm]?js|ts|[jt]sx)$/i.test(file.path);
888
1185
  const scriptContent = isHtml ? maskExceptInlineScripts(content) : content;
889
1186
  let matchable = isJsTs || isHtml ? maskRegexLiterals(scriptContent) : scriptContent;
890
1187
  if (isJsTs && isTestFile(file.path)) {
891
1188
  matchable = maskStringLiterals(matchable);
892
1189
  }
893
- if (SCANNABLE_EXTENSIONS.some((ext) => file.path.endsWith(ext))) {
1190
+ if (isSource || runsAsJs) {
894
1191
  fileContents.push({ path: file.path, content: matchable });
895
1192
  }
896
1193
  if (file.path.endsWith("package.json")) {
1194
+ try {
1195
+ const pkg = JSON.parse(content);
1196
+ if (typeof pkg.name === "string")
1197
+ localPackageNames.add(pkg.name);
1198
+ declaredDependencies.push(...npmDependencies(pkg, file.path));
1199
+ } catch {
1200
+ }
897
1201
  const pkgFindings = await scanPackageJson(content, maliciousPackages, file.path);
898
1202
  findings.push(...pkgFindings);
899
1203
  patternsMatched += pkgFindings.length;
@@ -908,7 +1212,7 @@ async function scanGitHubRepo(repo, options) {
908
1212
  patternsMatched += masquerade.length;
909
1213
  continue;
910
1214
  }
911
- if (!SCANNABLE_EXTENSIONS.some((ext) => file.path.endsWith(ext)) && (isConfigFile(file.path) || file.path.endsWith("package.json"))) {
1215
+ if (!isSource && (isConfigFile(file.path) || file.path.endsWith("package.json"))) {
912
1216
  const configFindings = applyYaraRules(content, yaraRules, file.path);
913
1217
  findings.push(...configFindings);
914
1218
  patternsMatched += configFindings.length;
@@ -919,12 +1223,13 @@ async function scanGitHubRepo(repo, options) {
919
1223
  }
920
1224
  }
921
1225
  if (file.path.endsWith("requirements.txt") || file.path.endsWith("setup.py")) {
1226
+ declaredDependencies.push(...pythonDependencies(content, file.path));
922
1227
  const pyFindings = scanPythonDeps(content, maliciousPackages, file.path);
923
1228
  findings.push(...pyFindings);
924
1229
  patternsMatched += pyFindings.length;
925
1230
  }
926
- if (SCANNABLE_EXTENSIONS.some((ext) => file.path.endsWith(ext))) {
927
- const ruleScopePath = isHtml ? `${file.path}.js` : file.path;
1231
+ if (isSource || runsAsJs) {
1232
+ const ruleScopePath = isHtml || runsAsJs ? `${file.path}.js` : file.path;
928
1233
  const yaraFindings = applyYaraRules(matchable, yaraRules, file.path, ruleScopePath);
929
1234
  findings.push(...yaraFindings);
930
1235
  patternsMatched += yaraFindings.length;
@@ -933,6 +1238,12 @@ async function scanGitHubRepo(repo, options) {
933
1238
  patternsMatched += obfuscationFindings.length;
934
1239
  }
935
1240
  }
1241
+ if (options.osvFeed) {
1242
+ const alreadyFlagged = new Set(findings.filter((finding) => finding.type === "SUSPICIOUS_DEPENDENCY" && finding.package).map((finding) => finding.package));
1243
+ const osvFindings = matchOsvFeed(options.osvFeed, declaredDependencies, localPackageNames, alreadyFlagged);
1244
+ findings.push(...osvFindings);
1245
+ patternsMatched += osvFindings.length;
1246
+ }
936
1247
  const sourceFiles = fileContents.filter((f) => !isTestFile(f.path));
937
1248
  const languageFindings = await detectNonEnglishComments(sourceFiles, repo);
938
1249
  findings.push(...languageFindings);
@@ -974,6 +1285,9 @@ async function scanGitHubRepo(repo, options) {
974
1285
  const integrityFindings = await detectCodeIntegrityIssues(fileContents, allPaths, repo);
975
1286
  findings.push(...integrityFindings);
976
1287
  patternsMatched += integrityFindings.length;
1288
+ const historyFindings = await fetchHistorySignals(`${repo.owner}/${repo.repo}`, branch, commitSha, headers);
1289
+ findings.push(...historyFindings);
1290
+ patternsMatched += historyFindings.length;
977
1291
  const rawRiskScore = calculateRawRiskScore(findings);
978
1292
  const riskScore = calculateRiskScore(findings);
979
1293
  const riskLevel = getRiskLevel(riskScore, findings);
@@ -1002,7 +1316,9 @@ async function scanGitHubRepo(repo, options) {
1002
1316
  scannedFiles,
1003
1317
  skippedFiles,
1004
1318
  skippedCount,
1005
- treeTruncated: tree.truncated
1319
+ treeTruncated: tree.truncated,
1320
+ complete: !rateLimited && fetchFailures === 0,
1321
+ ...rateLimited ? { incompleteReason: "rate-limit" } : fetchFailures > 0 ? { incompleteReason: "fetch-errors" } : {}
1006
1322
  },
1007
1323
  findings,
1008
1324
  safeToClone: cloneRiskLevel === "low",
@@ -1304,12 +1620,30 @@ function extractCodeSnippet(line, maxLength = 500) {
1304
1620
  }
1305
1621
  return line;
1306
1622
  }
1307
- var ENGLISH_CODES = ["eng", "sco"];
1308
- var MIN_WORD_LENGTH = 5;
1309
- var MIN_WORDS_TO_ANALYZE = 30;
1623
+ var LETTER = new RegExp("\\p{L}", "gu");
1624
+ var NON_LATIN_LETTER = new RegExp("(?!\\p{Script=Latin})\\p{L}", "gu");
1625
+ var NON_LATIN_SHARE_FOR_COMMENT = 0.5;
1626
+ var MIN_LETTERS_TO_ANALYZE = 150;
1310
1627
  var NON_ENGLISH_THRESHOLD = 0.25;
1311
- var MIN_NON_ENGLISH_WORDS = 8;
1312
- var MIN_COMMENT_LEN_FOR_DETECTION = 40;
1628
+ var MIN_NON_ENGLISH_LETTERS = 40;
1629
+ var COMMENT_DIRECTIVE = /^(?:eslint|@ts-|prettier-ignore|istanbul|c8\s|v8\s|jshint|tslint|biome-ignore|global\s|webpackChunkName|[#@]__PURE__|noinspection|type:\s*ignore|noqa|pylint:|fmt:|shellcheck)/i;
1630
+ var COMMENT_NON_PROSE = [
1631
+ /https?:\/\/\S+/g,
1632
+ /`[^`\n]*`/g,
1633
+ /@\w+(?:\s*\{[^}\n]{0,80}\})?/g,
1634
+ /(?<![\w$-])[\w$-]+(?:[.:/\\][\w$-]+)+/g,
1635
+ /\b[a-z]+[A-Z][\w$]*/g,
1636
+ /\b[\w$]*_[\w$]*/g,
1637
+ /[{}()[\]<>=;*#|"'+&!?^~\\-]+/g
1638
+ ];
1639
+ function commentProse(comment) {
1640
+ if (COMMENT_DIRECTIVE.test(comment))
1641
+ return null;
1642
+ let prose = comment;
1643
+ for (const pattern of COMMENT_NON_PROSE)
1644
+ prose = prose.replace(pattern, " ");
1645
+ return prose.replace(/\s+/g, " ").trim();
1646
+ }
1313
1647
  var COMMENT_PATTERNS = {
1314
1648
  javascript: [/\/\/(.*)$/gm, /\/\*[\s\S]*?\*\//g],
1315
1649
  typescript: [/\/\/(.*)$/gm, /\/\*[\s\S]*?\*\//g],
@@ -1343,40 +1677,38 @@ function extractComments(content, fileExtension) {
1343
1677
  return comments.map((comment) => comment.replace(/^\/\/\s*/, "").replace(/^\/\*\s*|\s*\*\/$/g, "").replace(/^#\s*/, "").replace(/^<#\s*|\s*#>$/g, "").replace(/^"""\s*|\s*"""$/g, "").replace(/^'''\s*|\s*'''$/g, "").replace(/^REM\s+/i, "").replace(/^::\s*/, "").trim()).filter((comment) => comment.length > 0);
1344
1678
  }
1345
1679
  function analyzeCommentLanguages(comments, filePath, fileAnalysis) {
1346
- let fileNonEnglishWords = 0;
1347
- for (const comment of comments) {
1348
- const words = comment.split(/\s+/).filter((word) => word.length >= MIN_WORD_LENGTH);
1349
- fileAnalysis.totalWords += words.length;
1680
+ let fileNonEnglishLetters = 0;
1681
+ for (const raw of comments) {
1682
+ const comment = commentProse(raw);
1683
+ if (!comment)
1684
+ continue;
1685
+ const letters = comment.match(LETTER)?.length ?? 0;
1686
+ if (letters === 0)
1687
+ continue;
1688
+ fileAnalysis.totalLetters += letters;
1350
1689
  fileAnalysis.totalComments += 1;
1351
- if (comment.length >= MIN_COMMENT_LEN_FOR_DETECTION) {
1352
- const detectedLang = franc(comment);
1353
- if (detectedLang && detectedLang !== "und") {
1354
- if (ENGLISH_CODES.includes(detectedLang)) {
1355
- fileAnalysis.englishWords += words.length;
1356
- } else {
1357
- fileAnalysis.nonEnglishWords += words.length;
1358
- fileNonEnglishWords += words.length;
1359
- const currentCount = fileAnalysis.detectedLanguages.get(detectedLang) || 0;
1360
- fileAnalysis.detectedLanguages.set(detectedLang, currentCount + words.length);
1361
- }
1362
- } else {
1363
- fileAnalysis.englishWords += words.length;
1364
- }
1365
- } else {
1366
- fileAnalysis.englishWords += words.length;
1690
+ const nonLatin = comment.match(NON_LATIN_LETTER)?.length ?? 0;
1691
+ if (nonLatin / letters < NON_LATIN_SHARE_FOR_COMMENT) {
1692
+ fileAnalysis.englishLetters += letters;
1693
+ continue;
1367
1694
  }
1695
+ const language = franc(comment, { minLength: 3 });
1696
+ const code = language === "und" ? "other" : language;
1697
+ fileAnalysis.nonEnglishLetters += letters;
1698
+ fileNonEnglishLetters += letters;
1699
+ fileAnalysis.detectedLanguages.set(code, (fileAnalysis.detectedLanguages.get(code) ?? 0) + letters);
1368
1700
  }
1369
- if (fileNonEnglishWords > 0) {
1370
- fileAnalysis.filesWithNonEnglish.set(filePath, fileNonEnglishWords);
1701
+ if (fileNonEnglishLetters > 0) {
1702
+ fileAnalysis.filesWithNonEnglish.set(filePath, fileNonEnglishLetters);
1371
1703
  }
1372
1704
  }
1373
1705
  async function detectNonEnglishComments(files, _repo) {
1374
1706
  const findings = [];
1375
1707
  const analysis = {
1376
1708
  totalComments: 0,
1377
- totalWords: 0,
1378
- englishWords: 0,
1379
- nonEnglishWords: 0,
1709
+ totalLetters: 0,
1710
+ englishLetters: 0,
1711
+ nonEnglishLetters: 0,
1380
1712
  nonEnglishPercentage: 0,
1381
1713
  detectedLanguages: /* @__PURE__ */ new Map(),
1382
1714
  filesWithNonEnglish: /* @__PURE__ */ new Map()
@@ -1388,21 +1720,20 @@ async function detectNonEnglishComments(files, _repo) {
1388
1720
  analyzeCommentLanguages(comments, file.path, analysis);
1389
1721
  }
1390
1722
  }
1391
- if (analysis.totalWords >= MIN_WORDS_TO_ANALYZE) {
1392
- analysis.nonEnglishPercentage = analysis.nonEnglishWords / analysis.totalWords;
1393
- if (analysis.nonEnglishPercentage >= NON_ENGLISH_THRESHOLD && analysis.nonEnglishWords >= MIN_NON_ENGLISH_WORDS) {
1723
+ if (analysis.totalLetters >= MIN_LETTERS_TO_ANALYZE) {
1724
+ analysis.nonEnglishPercentage = analysis.nonEnglishLetters / analysis.totalLetters;
1725
+ if (analysis.nonEnglishPercentage >= NON_ENGLISH_THRESHOLD && analysis.nonEnglishLetters >= MIN_NON_ENGLISH_LETTERS) {
1394
1726
  const topFiles = Array.from(analysis.filesWithNonEnglish.entries()).sort((a, b) => b[1] - a[1]).slice(0, 3).map(([path]) => path);
1395
- const langBreakdown = Array.from(analysis.detectedLanguages.entries()).map(([code, count]) => `${getLanguageName(code)}: ${count} words`).join(", ");
1396
- let severity = "medium";
1397
- let description = "";
1398
- if (analysis.englishWords === 0) {
1399
- severity = "high";
1400
- description = `100% of code comments are in non-English languages (${langBreakdown}). Repository contains NO English comments, which is highly suspicious for projects claiming international scope.`;
1401
- } else {
1402
- const percentage = Math.round(analysis.nonEnglishPercentage * 100);
1403
- description = `${percentage}% of code comments are in non-English languages (${langBreakdown}). This may indicate deceptive code where malicious intent is hidden in foreign language comments.`;
1404
- }
1405
- findings.push({ severity, type: "NON_ENGLISH_COMMENTS", description, files: topFiles });
1727
+ const langBreakdown = Array.from(analysis.detectedLanguages.entries()).sort((a, b) => b[1] - a[1]).map(([code, count]) => `${getLanguageName(code)}: ${count} characters`).join(", ");
1728
+ const percentage = Math.round(analysis.nonEnglishPercentage * 100);
1729
+ findings.push({
1730
+ severity: "low",
1731
+ confidence: "low",
1732
+ cloneBlocking: false,
1733
+ type: "NON_ENGLISH_COMMENTS",
1734
+ description: `${percentage}% of code comment text is in languages other than English (${langBreakdown}). Normal for many projects; shown for context only.`,
1735
+ files: topFiles
1736
+ });
1406
1737
  }
1407
1738
  }
1408
1739
  return findings;
@@ -1412,6 +1743,7 @@ function getLanguageName(code) {
1412
1743
  tur: "Turkish",
1413
1744
  rus: "Russian",
1414
1745
  zho: "Chinese",
1746
+ cmn: "Chinese",
1415
1747
  jpn: "Japanese",
1416
1748
  kor: "Korean",
1417
1749
  ara: "Arabic",
@@ -1427,7 +1759,12 @@ function getLanguageName(code) {
1427
1759
  tha: "Thai",
1428
1760
  ind: "Indonesian",
1429
1761
  heb: "Hebrew",
1430
- hin: "Hindi"
1762
+ hin: "Hindi",
1763
+ zlm: "Malay",
1764
+ ron: "Romanian",
1765
+ arb: "Arabic",
1766
+ bel: "Belarusian",
1767
+ other: "Other"
1431
1768
  };
1432
1769
  return names[code] || code;
1433
1770
  }
@@ -2322,6 +2659,94 @@ function describeSource(loaded) {
2322
2659
  }
2323
2660
  }
2324
2661
 
2662
+ // src/lib/osv-feed.ts
2663
+ import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
2664
+ import { homedir as homedir2 } from "os";
2665
+ import { join as join2 } from "path";
2666
+ var DEFAULT_OSV_FEED_URL = "https://raw.githubusercontent.com/flagrix-io/flagrix-detection-rules/main/osv-malicious.json";
2667
+ var CACHE_TTL_MS2 = 6 * 60 * 60 * 1e3;
2668
+ function feedUrl() {
2669
+ return process.env.FLAGRIX_OSV_FEED_URL || DEFAULT_OSV_FEED_URL;
2670
+ }
2671
+ function cacheFilePath2() {
2672
+ const base = process.env.FLAGRIX_CACHE_DIR || process.env.XDG_CACHE_HOME || join2(homedir2(), ".cache");
2673
+ return join2(base, "flagrix", "osv-malicious.json");
2674
+ }
2675
+ function isFeed(data2) {
2676
+ return data2?.schemaVersion === 1 && Array.isArray(data2.npm?.all) && typeof data2.npm?.versions === "object" && Array.isArray(data2.pypi?.all) && typeof data2.pypi?.versions === "object";
2677
+ }
2678
+ async function readCache2() {
2679
+ try {
2680
+ return JSON.parse(await readFile2(cacheFilePath2(), "utf8"));
2681
+ } catch {
2682
+ return null;
2683
+ }
2684
+ }
2685
+ async function writeCache2(entry) {
2686
+ try {
2687
+ const path = cacheFilePath2();
2688
+ await mkdir2(join2(path, ".."), { recursive: true });
2689
+ await writeFile2(path, JSON.stringify(entry));
2690
+ } catch {
2691
+ }
2692
+ }
2693
+ async function loadOsvFeed() {
2694
+ if (process.env.FLAGRIX_OSV_FEED === "0") return void 0;
2695
+ const cached = await readCache2();
2696
+ const cachedFeed = cached && isFeed(cached.data) ? cached.data : void 0;
2697
+ if (cachedFeed && Date.now() - new Date(cached.fetchedAt).getTime() < CACHE_TTL_MS2) {
2698
+ return cachedFeed;
2699
+ }
2700
+ try {
2701
+ const response = await fetch(feedUrl(), {
2702
+ headers: cachedFeed && cached?.etag ? { "If-None-Match": cached.etag } : {}
2703
+ });
2704
+ if (response.status === 304 && cachedFeed) {
2705
+ await writeCache2({ ...cached, fetchedAt: (/* @__PURE__ */ new Date()).toISOString() });
2706
+ return cachedFeed;
2707
+ }
2708
+ if (response.ok) {
2709
+ const data2 = await response.json();
2710
+ if (isFeed(data2)) {
2711
+ await writeCache2({
2712
+ fetchedAt: (/* @__PURE__ */ new Date()).toISOString(),
2713
+ etag: response.headers.get("etag") ?? void 0,
2714
+ data: data2
2715
+ });
2716
+ return data2;
2717
+ }
2718
+ }
2719
+ } catch {
2720
+ }
2721
+ return cachedFeed;
2722
+ }
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
+
2325
2750
  // src/lib/render.ts
2326
2751
  var useColor = process.stdout.isTTY && !process.env.NO_COLOR;
2327
2752
  var paint = (code) => (s) => useColor ? `\x1B[${code}m${s}\x1B[0m` : s;
@@ -2335,24 +2760,49 @@ var VERDICTS = {
2335
2760
  medium: { label: "MEDIUM RISK", verdict: "Review before cloning", color: yellow },
2336
2761
  high: { label: "HIGH RISK", verdict: "Do not clone", color: red }
2337
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
+ }
2338
2777
  function securityScore(riskScore) {
2339
2778
  return 100 - Math.round(riskScore * 100);
2340
2779
  }
2341
2780
  function renderRepoResult(result) {
2342
2781
  const v = VERDICTS[result.riskLevel];
2782
+ const coverage = coverageOf(result);
2343
2783
  const slug = `${result.repo.owner}/${result.repo.repo}`;
2344
2784
  const sha = result.commitSha?.slice(0, 7);
2345
2785
  const lines = [];
2346
2786
  lines.push("");
2347
2787
  lines.push(` ${bold(slug)}${sha ? dim(` @ ${sha}`) : ""}`);
2348
- lines.push(
2349
- ` ${v.color(bold(`${v.label} \u2014 ${v.verdict}`))} ${dim(`security score ${securityScore(result.riskScore)}/100`)}`
2350
- );
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
+ }
2351
2797
  lines.push(
2352
2798
  dim(
2353
2799
  ` ${result.scanSummary.filesScanned} files scanned \xB7 ${result.scanSummary.dependenciesChecked} dependencies \xB7 ${result.findings.length} issue${result.findings.length === 1 ? "" : "s"}`
2354
2800
  )
2355
2801
  );
2802
+ if (!coverage.complete) {
2803
+ lines.push("");
2804
+ for (const line of wrapNote(describeCoverage(coverage), " ")) lines.push(yellow(line));
2805
+ }
2356
2806
  for (const f of result.findings) {
2357
2807
  lines.push("");
2358
2808
  lines.push(` ${bold(f.severity.toUpperCase())} ${f.description}`);
@@ -2399,10 +2849,13 @@ function renderUserResult(result) {
2399
2849
  }
2400
2850
 
2401
2851
  // src/commands/shared.ts
2402
- var EXIT = { LOW: 0, ERROR: 1, MEDIUM: 2, HIGH: 3 };
2852
+ var EXIT = { LOW: 0, ERROR: 1, MEDIUM: 2, HIGH: 3, INCOMPLETE: 4 };
2403
2853
  function exitCodeFor(level) {
2404
2854
  return level === "high" ? EXIT.HIGH : level === "medium" ? EXIT.MEDIUM : EXIT.LOW;
2405
2855
  }
2856
+ function exitCodeForScan(result) {
2857
+ return coverageOf(result).unreliableClear ? EXIT.INCOMPLETE : exitCodeFor(result.riskLevel);
2858
+ }
2406
2859
  function resolveToken(flag) {
2407
2860
  return flag || process.env.FLAGRIX_GITHUB_TOKEN || process.env.GITHUB_TOKEN || void 0;
2408
2861
  }
@@ -2416,11 +2869,15 @@ export {
2416
2869
  parseRepoTarget,
2417
2870
  loadSignatures,
2418
2871
  describeSource,
2872
+ loadOsvFeed,
2873
+ coverageOf,
2874
+ describeCoverage,
2419
2875
  securityScore,
2420
2876
  renderRepoResult,
2421
2877
  renderUserResult,
2422
2878
  EXIT,
2423
2879
  exitCodeFor,
2880
+ exitCodeForScan,
2424
2881
  resolveToken,
2425
2882
  wantJson
2426
2883
  };
package/dist/cli.js CHANGED
@@ -3,6 +3,8 @@ import {
3
3
  EXIT,
4
4
  describeSource,
5
5
  exitCodeFor,
6
+ exitCodeForScan,
7
+ loadOsvFeed,
6
8
  loadSignatures,
7
9
  parseRepoTarget,
8
10
  renderRepoResult,
@@ -11,7 +13,7 @@ import {
11
13
  scanGitHubRepo,
12
14
  scanGitHubUser,
13
15
  wantJson
14
- } from "./chunk-EBYRT2M7.js";
16
+ } from "./chunk-XBQCLZNK.js";
15
17
 
16
18
  // src/cli.ts
17
19
  import { parseArgs } from "util";
@@ -29,16 +31,18 @@ async function runScan(target, options) {
29
31
  const loaded = await loadSignatures();
30
32
  const note = describeSource(loaded);
31
33
  if (note) console.error(`flagrix: ${note}`);
32
- const result = await scanGitHubRepo(repo, {
34
+ const scanOptions = {
33
35
  signatures: loaded.signatures,
34
- githubToken: resolveToken(options.token)
35
- });
36
+ githubToken: resolveToken(options.token),
37
+ osvFeed: await loadOsvFeed()
38
+ };
39
+ const result = await scanGitHubRepo(repo, scanOptions);
36
40
  if (wantJson(options.json)) {
37
41
  console.log(JSON.stringify(result, null, 2));
38
42
  } else {
39
43
  console.log(renderRepoResult(result));
40
44
  }
41
- return exitCodeFor(result.riskLevel);
45
+ return exitCodeForScan(result);
42
46
  } catch (error) {
43
47
  console.error(`flagrix: scan failed \u2014 ${error.message}`);
44
48
  return EXIT.ERROR;
@@ -73,7 +77,7 @@ async function runScanUser(login, options) {
73
77
  }
74
78
 
75
79
  // src/cli.ts
76
- var VERSION = "0.1.0";
80
+ var VERSION = "0.4.0";
77
81
  var HELP = `flagrix \u2014 scan GitHub repos and profiles for malware before you clone
78
82
 
79
83
  Usage:
@@ -91,10 +95,15 @@ Options:
91
95
  Exit codes:
92
96
  0 low risk 2 medium risk \u2014 review before proceeding
93
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
94
99
 
95
100
  The verdict is pinned to the scanned commit SHA (in the JSON output as
96
- "commitSha"). Scanning is fully local: the only network calls go to the
97
- 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.
98
107
  Docs: https://github.com/flagrix-io/flagrix-cli`;
99
108
  async function main() {
100
109
  const { values, positionals } = parseArgs({
@@ -132,7 +141,7 @@ async function main() {
132
141
  }
133
142
  return runScanUser(target, { json: values.json, token: values.token });
134
143
  case "mcp": {
135
- const { runMcp } = await import("./mcp-7DWCHBWC.js");
144
+ const { runMcp } = await import("./mcp-EHS7B5VR.js");
136
145
  return runMcp();
137
146
  }
138
147
  default:
@@ -1,13 +1,16 @@
1
1
  #!/usr/bin/env node
2
2
  import {
3
+ coverageOf,
4
+ describeCoverage,
3
5
  describeSource,
6
+ loadOsvFeed,
4
7
  loadSignatures,
5
8
  parseRepoTarget,
6
9
  resolveToken,
7
10
  scanGitHubRepo,
8
11
  scanGitHubUser,
9
12
  securityScore
10
- } from "./chunk-EBYRT2M7.js";
13
+ } from "./chunk-XBQCLZNK.js";
11
14
 
12
15
  // src/commands/mcp.ts
13
16
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -18,8 +21,27 @@ var GUIDANCE = {
18
21
  medium: "MEDIUM risk: do NOT clone, install, or execute this code until a human has reviewed the findings.",
19
22
  high: "HIGH risk: do NOT clone, install, or execute this code. Treat the repository as malicious."
20
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
+ }
21
43
  async function runMcp() {
22
- const server = new McpServer({ name: "flagrix", version: "0.1.0" });
44
+ const server = new McpServer({ name: "flagrix", version: "0.4.0" });
23
45
  server.registerTool(
24
46
  "scan_github_repo",
25
47
  {
@@ -33,23 +55,13 @@ async function runMcp() {
33
55
  async ({ target, ref }) => {
34
56
  const repo = parseRepoTarget(target, ref);
35
57
  const loaded = await loadSignatures();
36
- const result = await scanGitHubRepo(repo, {
58
+ const scanOptions = {
37
59
  signatures: loaded.signatures,
38
- githubToken: resolveToken()
39
- });
40
- const note = describeSource(loaded);
41
- const summary = [
42
- `${result.riskLevel.toUpperCase()} risk \u2014 security score ${securityScore(result.riskScore)}/100 (verdict pinned to commit ${result.commitSha ?? "unknown"}).`,
43
- GUIDANCE[result.riskLevel],
44
- ...note ? [`Note: ${note}.`] : []
45
- ].join(" ");
46
- return {
47
- content: [
48
- { type: "text", text: summary },
49
- { type: "text", text: JSON.stringify(result, null, 2) }
50
- ],
51
- isError: false
60
+ githubToken: resolveToken(),
61
+ osvFeed: await loadOsvFeed()
52
62
  };
63
+ const result = await scanGitHubRepo(repo, scanOptions);
64
+ return repoScanResponse(result, describeSource(loaded));
53
65
  }
54
66
  );
55
67
  server.registerTool(
@@ -84,5 +96,6 @@ async function runMcp() {
84
96
  return 0;
85
97
  }
86
98
  export {
99
+ repoScanResponse,
87
100
  runMcp
88
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.2.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.4.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",