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