flagrix 0.4.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -37,7 +37,7 @@ flagrix mcp # MCP server (stdio) for AI agents
37
37
  | 1 | scan failed |
38
38
  | 2 | medium risk — review before proceeding |
39
39
  | 3 | high risk — do not clone |
40
- | 4 | scan incomplete — too little was read to call the repository safe |
40
+ | 4 | scan incomplete — not enough of the repository was read to give a verdict |
41
41
 
42
42
  `--json` (automatic when stdout is piped) emits the full result. The verdict is
43
43
  **pinned to the scanned commit** (`commitSha` in the JSON): every file is read at
@@ -60,6 +60,39 @@ are the other way round: evidence found is evidence however little else was
60
60
  read, so a medium or high verdict keeps its own code and the coverage note
61
61
  reads "there may be more".
62
62
 
63
+ In `--json` output, read `verdict` and `coverage` rather than `riskLevel`:
64
+
65
+ ```json
66
+ {
67
+ "verdict": "incomplete",
68
+ "coverage": {
69
+ "complete": false,
70
+ "unreliableClear": true,
71
+ "filesRead": 30,
72
+ "filesUnread": 150,
73
+ "reason": "rate-limit"
74
+ },
75
+ "riskLevel": "low",
76
+ "safeToClone": false,
77
+ ...
78
+ }
79
+ ```
80
+
81
+ - `verdict` is `"low"`, `"medium"`, `"high"`, or `"incomplete"` when a low
82
+ result rests on files that were never read. It matches the exit code
83
+ (0 / 2 / 3 / 4).
84
+ - `coverage.unreliableClear` is true exactly when `verdict` is `"incomplete"`;
85
+ `coverage.complete` is false on any partial scan, including a medium or high
86
+ one. `reason` is present only when coverage is incomplete.
87
+ - `riskLevel`, `riskScore` and the rest of the engine's result are unchanged,
88
+ so existing consumers keep working — but `riskLevel` is the engine's reading
89
+ of the files it did see, so on an incomplete scan it can still say `"low"`.
90
+ - `safeToClone` is kept for compatibility and is now `false` whenever
91
+ `verdict` is `"incomplete"` (in 0.4.0 and earlier it could be `true` there). Gate on
92
+ `verdict` or the exit code instead.
93
+
94
+ The MCP tool's JSON block carries the same fields.
95
+
63
96
  Set a token to make this rare: `GITHUB_TOKEN` raises the budget to 5,000/h.
64
97
 
65
98
  ## AI agents
@@ -1,6 +1,6 @@
1
1
  {
2
- "version": "2026.10.19.001",
3
- "lastUpdated": "2026-10-19T19:29:18.424Z",
2
+ "version": "2026.11.10.001",
3
+ "lastUpdated": "2026-11-10T16:39:28.787Z",
4
4
  "maliciousPackages": [
5
5
  {
6
6
  "name": "beavertail",
@@ -897,9 +897,9 @@
897
897
  },
898
898
  {
899
899
  "id": "BACKDOOR_HARDCODED_AUTH",
900
- "name": "Hardcoded Auth Bypass",
900
+ "name": "Hardcoded Password Comparison",
901
901
  "pattern": "(?:password|auth)\\s*(?:===?|==)\\s*['\"][^'\"]{0,20}['\"]\\s*\\)",
902
- "description": "Hardcoded password check — always-true backdoor condition in auth logic",
902
+ "description": "Password or auth value compared against a hardcoded string literal (e.g. password == \"admin123\") — a pattern backdoors use, but also common in tests, examples and placeholder checks",
903
903
  "tags": [
904
904
  "backdoor",
905
905
  "auth-bypass",
@@ -2736,11 +2736,20 @@ function coverageOf(result) {
2736
2736
  reason: summary.incompleteReason
2737
2737
  };
2738
2738
  }
2739
- function describeCoverage(coverage) {
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, findingCount) {
2740
2749
  if (coverage.complete) return "";
2741
2750
  const read = `${coverage.filesRead} ${coverage.filesRead === 1 ? "file" : "files"} read`;
2742
2751
  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.";
2752
+ const consequence = !coverage.unreliableClear ? "There may be more than what is reported here." : findingCount > 0 ? "What was read turned up only low-weight findings \u2014 that says nothing about the files left unread." : "Nothing was found in what was read \u2014 that is not the same as nothing being there.";
2744
2753
  if (coverage.reason === "rate-limit") {
2745
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}`;
2746
2755
  }
@@ -2756,7 +2765,7 @@ var red = paint("31");
2756
2765
  var yellow = paint("33");
2757
2766
  var green = paint("32");
2758
2767
  var VERDICTS = {
2759
- low: { label: "LOW RISK", verdict: "Safe to clone", color: green },
2768
+ low: { label: "LOW RISK", verdict: "No blocking findings", color: green },
2760
2769
  medium: { label: "MEDIUM RISK", verdict: "Review before cloning", color: yellow },
2761
2770
  high: { label: "HIGH RISK", verdict: "Do not clone", color: red }
2762
2771
  };
@@ -2787,7 +2796,7 @@ function renderRepoResult(result) {
2787
2796
  lines.push(` ${bold(slug)}${sha ? dim(` @ ${sha}`) : ""}`);
2788
2797
  if (coverage.unreliableClear) {
2789
2798
  lines.push(
2790
- ` ${yellow(bold("SCAN INCOMPLETE \u2014 no verdict"))} ${dim("too little of this repository was read to call it safe")}`
2799
+ ` ${yellow(bold("SCAN INCOMPLETE \u2014 no verdict"))} ${dim("not enough of this repository was read to give a verdict")}`
2791
2800
  );
2792
2801
  } else {
2793
2802
  lines.push(
@@ -2801,7 +2810,7 @@ function renderRepoResult(result) {
2801
2810
  );
2802
2811
  if (!coverage.complete) {
2803
2812
  lines.push("");
2804
- for (const line of wrapNote(describeCoverage(coverage), " ")) lines.push(yellow(line));
2813
+ for (const line of wrapNote(describeCoverage(coverage, result.findings.length), " ")) lines.push(yellow(line));
2805
2814
  }
2806
2815
  for (const f of result.findings) {
2807
2816
  lines.push("");
@@ -2871,6 +2880,7 @@ export {
2871
2880
  describeSource,
2872
2881
  loadOsvFeed,
2873
2882
  coverageOf,
2883
+ scanReport,
2874
2884
  describeCoverage,
2875
2885
  securityScore,
2876
2886
  renderRepoResult,
package/dist/cli.js CHANGED
@@ -12,8 +12,9 @@ import {
12
12
  resolveToken,
13
13
  scanGitHubRepo,
14
14
  scanGitHubUser,
15
+ scanReport,
15
16
  wantJson
16
- } from "./chunk-XBQCLZNK.js";
17
+ } from "./chunk-HL53V2DT.js";
17
18
 
18
19
  // src/cli.ts
19
20
  import { parseArgs } from "util";
@@ -38,7 +39,7 @@ async function runScan(target, options) {
38
39
  };
39
40
  const result = await scanGitHubRepo(repo, scanOptions);
40
41
  if (wantJson(options.json)) {
41
- console.log(JSON.stringify(result, null, 2));
42
+ console.log(JSON.stringify(scanReport(result), null, 2));
42
43
  } else {
43
44
  console.log(renderRepoResult(result));
44
45
  }
@@ -77,7 +78,7 @@ async function runScanUser(login, options) {
77
78
  }
78
79
 
79
80
  // src/cli.ts
80
- var VERSION = "0.4.0";
81
+ var VERSION = "0.5.1";
81
82
  var HELP = `flagrix \u2014 scan GitHub repos and profiles for malware before you clone
82
83
 
83
84
  Usage:
@@ -95,15 +96,15 @@ Options:
95
96
  Exit codes:
96
97
  0 low risk 2 medium risk \u2014 review before proceeding
97
98
  1 scan failed 3 high risk \u2014 do not clone
98
- 4 scan incomplete \u2014 too little of the repository was read to call it safe
99
+ 4 scan incomplete \u2014 not enough of the repository was read to give a verdict
99
100
 
100
101
  The verdict is pinned to the scanned commit SHA (in the JSON output as
101
102
  "commitSha"). A scan that runs out of GitHub API budget reports partial
102
- coverage ("scanSummary.complete": false) and exits 4 rather than 0: unread
103
- files cannot clear a repository. Findings still stand on partial coverage,
104
- so medium and high keep their own codes. Scanning is fully local: the only
105
- network calls go to the GitHub/npm APIs and the public detection-rules
106
- repository. No telemetry.
103
+ coverage ("verdict": "incomplete", "coverage": {...}) and exits 4 rather
104
+ than 0: unread files cannot clear a repository. Findings still stand on
105
+ partial coverage, so medium and high keep their own codes. Scanning is fully
106
+ local: the only network calls go to the GitHub/npm APIs and the public
107
+ detection-rules repository. No telemetry.
107
108
  Docs: https://github.com/flagrix-io/flagrix-cli`;
108
109
  async function main() {
109
110
  const { values, positionals } = parseArgs({
@@ -141,7 +142,7 @@ async function main() {
141
142
  }
142
143
  return runScanUser(target, { json: values.json, token: values.token });
143
144
  case "mcp": {
144
- const { runMcp } = await import("./mcp-EHS7B5VR.js");
145
+ const { runMcp } = await import("./mcp-KMJZQ5JQ.js");
145
146
  return runMcp();
146
147
  }
147
148
  default:
@@ -9,8 +9,9 @@ import {
9
9
  resolveToken,
10
10
  scanGitHubRepo,
11
11
  scanGitHubUser,
12
+ scanReport,
12
13
  securityScore
13
- } from "./chunk-XBQCLZNK.js";
14
+ } from "./chunk-HL53V2DT.js";
14
15
 
15
16
  // src/commands/mcp.ts
16
17
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -21,7 +22,7 @@ var GUIDANCE = {
21
22
  medium: "MEDIUM risk: do NOT clone, install, or execute this code until a human has reviewed the findings.",
22
23
  high: "HIGH risk: do NOT clone, install, or execute this code. Treat the repository as malicious."
23
24
  };
24
- var INCOMPLETE_GUIDANCE = "NO VERDICT: too little of this repository was read to call it safe, so this is NOT a clean result. Do NOT clone, install, or execute this code until a complete scan succeeds (set GITHUB_TOKEN and scan again) or a human has reviewed it.";
25
+ var INCOMPLETE_GUIDANCE = "NO VERDICT: only part of this repository was read, so this is NOT a clean result. Do NOT clone, install, or execute this code until a complete scan succeeds (set GITHUB_TOKEN and scan again) or a human has reviewed it.";
25
26
  function repoScanResponse(result, note) {
26
27
  const coverage = coverageOf(result);
27
28
  const pinned = `(verdict pinned to commit ${result.commitSha ?? "unknown"})`;
@@ -29,19 +30,19 @@ function repoScanResponse(result, note) {
29
30
  const summary = [
30
31
  headline,
31
32
  coverage.unreliableClear ? INCOMPLETE_GUIDANCE : GUIDANCE[result.riskLevel],
32
- ...coverage.complete ? [] : [describeCoverage(coverage)],
33
+ ...coverage.complete ? [] : [describeCoverage(coverage, result.findings.length)],
33
34
  ...note ? [`Note: ${note}.`] : []
34
35
  ].join(" ");
35
36
  return {
36
37
  content: [
37
38
  { type: "text", text: summary },
38
- { type: "text", text: JSON.stringify(result, null, 2) }
39
+ { type: "text", text: JSON.stringify(scanReport(result), null, 2) }
39
40
  ],
40
41
  isError: false
41
42
  };
42
43
  }
43
44
  async function runMcp() {
44
- const server = new McpServer({ name: "flagrix", version: "0.4.0" });
45
+ const server = new McpServer({ name: "flagrix", version: "0.5.1" });
45
46
  server.registerTool(
46
47
  "scan_github_repo",
47
48
  {
@@ -2,7 +2,8 @@
2
2
 
3
3
  Two ways to put Flagrix between an AI agent and untrusted code: the **MCP server**
4
4
  (the agent decides to scan, or is instructed to) and the **Claude Code hook**
5
- (every `git clone` is gated, no cooperation needed).
5
+ (recognized `git clone` / `gh repo clone` commands are gated, no cooperation
6
+ needed).
6
7
 
7
8
  ## Exit codes (the contract)
8
9
 
@@ -12,10 +13,24 @@ Two ways to put Flagrix between an AI agent and untrusted code: the **MCP server
12
13
  | 1 | scan failed (network, auth, bad target) |
13
14
  | 2 | medium risk — review before proceeding |
14
15
  | 3 | high risk — do not clone |
16
+ | 4 | scan incomplete — a low result over files that were never read; no verdict |
15
17
 
16
18
  `--json` (or any piped stdout) emits the full scan result, including `commitSha` —
17
19
  the verdict applies to that commit, not to whatever the branch points at later.
18
20
 
21
+ If you gate on the JSON instead of the exit code, branch on `verdict`
22
+ (`"low" | "medium" | "high" | "incomplete"`, matching exit 0 / 2 / 3 / 4) and
23
+ proceed only on `"low"`. Don't gate on `riskLevel`: it is the engine's reading
24
+ of the files it managed to read, so a scan that ran out of GitHub budget can
25
+ still report `"low"` there. `coverage` (`complete`, `unreliableClear`,
26
+ `filesRead`, `filesUnread`, `reason`) says how much was read and why the rest
27
+ wasn't. `safeToClone` is kept for older consumers and is `false` on an
28
+ incomplete scan, but `verdict` is the field to use. The `scan_github_repo` MCP
29
+ tool returns the same JSON as its second content block.
30
+
31
+ `scan-user` is unaffected: a profile scan either fetches everything it needs or
32
+ fails with exit 1, so it never returns a partial result.
33
+
19
34
  ## MCP server
20
35
 
21
36
  ```bash
@@ -58,6 +73,22 @@ Copies of the hook script ship inside the npm package (`hooks/flagrix-clone-gate
58
73
  Install the package globally first (`npm i -g flagrix`), or vendor the script into
59
74
  your repo and point the hook at it. The hook only reacts to `git clone` /
60
75
  `gh repo clone` commands targeting github.com; everything else passes through.
76
+ Git options before the subcommand are recognized (`git -C <dir> clone …`,
77
+ `git -c <key>=<value> clone …`, `git --git-dir=<dir> clone …`). It reads the
78
+ command text, not what the shell will run, so a clone hidden behind an alias,
79
+ a variable, a script or another tool (`curl … | sh`, a Makefile target) is not
80
+ seen. Treat it as a guard for an agent's ordinary clone commands, not a
81
+ sandbox.
82
+
83
+ What it scans: the branch the clone will check out. A `--branch <name>`,
84
+ `--branch=<name>` or `-b <name>` on the clone (including after `--` in
85
+ `gh repo clone owner/repo -- -b <name>`) is passed to the scan as `--ref`;
86
+ without one, the repository's default branch is scanned, which is what a plain
87
+ clone checks out. The verdict applies to the commit that ref pointed at when
88
+ the scan ran, so a push between the scan and the clone is not covered. Other
89
+ branches and tags the clone fetches but doesn't check out are not scanned, and
90
+ neither is anything you check out afterwards — scan those with
91
+ `npx flagrix scan <repo> --ref <ref>`.
61
92
 
62
93
  ## CI
63
94
 
@@ -69,5 +100,5 @@ your repo and point the hook at it. The hook only reacts to `git clone` /
69
100
  ```
70
101
 
71
102
  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
103
+ scan read too little of the repository to give a verdict — commonly GitHub's
73
104
  60 req/h limit, which `GITHUB_TOKEN` above raises to 5,000/h).
@@ -3,41 +3,73 @@
3
3
  #
4
4
  # Scans any GitHub repo about to be cloned; blocks the clone (hook exit 2)
5
5
  # when Flagrix rates it MEDIUM or HIGH risk, or when the scan could not read
6
- # enough of the repository to call it safe (exit 4). See docs/agent-gating.md
7
- # for the settings.json wiring.
6
+ # enough of the repository to give a verdict (exit 4). A `--branch`/`-b` on the
7
+ # clone is scanned as that ref; otherwise the repository's default branch is.
8
+ # See docs/agent-gating.md for the settings.json wiring.
8
9
  set -euo pipefail
9
10
 
10
11
  payload="$(cat)"
11
12
 
12
- # Extract a github.com repo URL from a `git clone`/`gh repo clone` command.
13
- url="$(node -e '
13
+ # Extract a github.com repo URL — and the branch, if one is given — from a
14
+ # `git clone`/`gh repo clone` command. Prints "<url>\t<branch>" (branch may be
15
+ # empty), or nothing when the command is not a GitHub clone.
16
+ parsed="$(node -e '
14
17
  let input = ""
15
18
  process.stdin.on("data", (d) => (input += d))
16
19
  process.stdin.on("end", () => {
17
20
  try {
18
21
  const cmd = JSON.parse(input)?.tool_input?.command ?? ""
19
- if (!/\b(git\s+clone|gh\s+repo\s+clone)\b/.test(cmd)) return
22
+ // git takes global options before the subcommand (`git -C /tmp clone …`,
23
+ // `git -c http.proxy=… clone …`, `git --git-dir=… clone …`), so allow any
24
+ // run of them between `git` and `clone`.
25
+ const VALUE = String.raw`(?:"[^"]*"|\x27[^\x27]*\x27|\S+)`
26
+ const GIT_OPTS =
27
+ String.raw`(?:\s+(?:-[Cc]\s+|--(?:git-dir|work-tree|namespace|exec-path|config-env)\s+)` +
28
+ VALUE +
29
+ String.raw`|\s+--?[\w-]+(?:=` + VALUE + String.raw`)?)*`
30
+ const clone = cmd.match(
31
+ new RegExp(String.raw`\bgit` + GIT_OPTS + String.raw`\s+clone\b|\bgh\s+repo\s+clone\b`)
32
+ )
33
+ if (!clone) return
20
34
  const m =
21
35
  cmd.match(/https?:\/\/github\.com\/[\w.-]+\/[\w.-]+/) ||
22
36
  cmd.match(/git@github\.com:[\w.-]+\/[\w.-]+/) ||
23
37
  cmd.match(/\bclone\s+([\w.-]+\/[\w.-]+)(?:\s|$)/)?.slice(1)
24
- if (m) process.stdout.write(String(Array.isArray(m) ? m[0] : m))
38
+ if (!m) return
39
+ // Only the clone itself counts: `git checkout -b x && git clone …` must
40
+ // not pick up the checkout branch. `gh repo clone o/r -- -b x` passes
41
+ // the flag through to git, so it is covered too.
42
+ const segment = cmd.slice(clone.index).split(/&&|\|\||[;|\n]/)[0]
43
+ const b = segment.match(/(?:^|\s)(?:--branch(?:=|\s+)|-b\s*)("[^"]+"|\x27[^\x27]+\x27|[^\s"\x27]+)/)
44
+ const branch = b ? b[1].replace(/^["\x27]|["\x27]$/g, "") : ""
45
+ process.stdout.write(String(Array.isArray(m) ? m[0] : m) + "\t" + branch)
25
46
  } catch {}
26
47
  })
27
48
  ' <<< "$payload")"
28
49
 
29
50
  # Not a GitHub clone — allow.
30
- [ -z "$url" ] && exit 0
51
+ [ -z "$parsed" ] && exit 0
31
52
 
32
- if npx -y flagrix scan "$url" --json > /dev/null 2>&1; then
53
+ url="${parsed%%$'\t'*}"
54
+ ref="${parsed#*$'\t'}"
55
+
56
+ args=(scan "$url" --json)
57
+ target="$url"
58
+ if [ -n "$ref" ]; then
59
+ args+=(--ref "$ref")
60
+ target="$url (branch $ref)"
61
+ fi
62
+
63
+ if npx -y flagrix "${args[@]}" > /dev/null 2>&1; then
33
64
  exit 0 # low risk
34
65
  else
35
66
  code=$?
67
+ rerun="npx flagrix scan $url${ref:+ --ref $ref}"
36
68
  case "$code" in
37
- 2) echo "Flagrix: MEDIUM risk — review https://github.com/flagrix-io/flagrix-cli#exit-codes before cloning $url" >&2 ;;
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 ;;
40
- *) echo "Flagrix: scan of $url failed (exit $code) — blocking out of caution. Run: npx flagrix scan $url" >&2 ;;
69
+ 2) echo "Flagrix: MEDIUM risk — review https://github.com/flagrix-io/flagrix-cli#exit-codes before cloning $target" >&2 ;;
70
+ 3) echo "Flagrix: HIGH risk — do NOT clone $target (malicious patterns detected). Run: $rerun" >&2 ;;
71
+ 4) echo "Flagrix: scan of $target was incomplete — not enough was read to give a verdict (usually GitHub's 60 req/h limit; set GITHUB_TOKEN). Run: $rerun" >&2 ;;
72
+ *) echo "Flagrix: scan of $target failed (exit $code) — blocking out of caution. Run: $rerun" >&2 ;;
41
73
  esac
42
74
  exit 2 # exit 2 = block the tool call in Claude Code
43
75
  fi
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "flagrix",
3
- "version": "0.4.0",
3
+ "version": "0.5.1",
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",