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