flagrix 0.1.0

package/dist/cli.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+import {
+  EXIT,
+  describeSource,
+  exitCodeFor,
+  loadSignatures,
+  parseRepoTarget,
+  renderRepoResult,
+  renderUserResult,
+  resolveToken,
+  scanGitHubRepo,
+  scanGitHubUser,
+  wantJson
+} from "./chunk-FJUDM3F7.js";
+
+// src/cli.ts
+import { parseArgs } from "util";
+
+// src/commands/scan.ts
+async function runScan(target, options) {
+  let repo;
+  try {
+    repo = parseRepoTarget(target, options.ref);
+  } catch (error) {
+    console.error(`flagrix: ${error.message}`);
+    return EXIT.ERROR;
+  }
+  try {
+    const loaded = await loadSignatures();
+    const note = describeSource(loaded);
+    if (note) console.error(`flagrix: ${note}`);
+    const result = await scanGitHubRepo(repo, {
+      signatures: loaded.signatures,
+      githubToken: resolveToken(options.token)
+    });
+    if (wantJson(options.json)) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(renderRepoResult(result));
+    }
+    return exitCodeFor(result.riskLevel);
+  } catch (error) {
+    console.error(`flagrix: scan failed \u2014 ${error.message}`);
+    return EXIT.ERROR;
+  }
+}
+
+// src/commands/scan-user.ts
+async function runScanUser(login, options) {
+  const username = login.trim().replace(/^https?:\/\/(www\.)?github\.com\//, "").replace(/\/.*$/, "");
+  if (!/^[A-Za-z0-9-]+$/.test(username)) {
+    console.error(`flagrix: not a GitHub username: "${login}"`);
+    return EXIT.ERROR;
+  }
+  try {
+    const loaded = await loadSignatures();
+    const note = describeSource(loaded);
+    if (note) console.error(`flagrix: ${note}`);
+    const result = await scanGitHubUser(username, {
+      githubToken: resolveToken(options.token),
+      userProfileRules: loaded.signatures.userProfileRules
+    });
+    if (wantJson(options.json)) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(renderUserResult(result));
+    }
+    return exitCodeFor(result.riskLevel);
+  } catch (error) {
+    console.error(`flagrix: profile scan failed \u2014 ${error.message}`);
+    return EXIT.ERROR;
+  }
+}
+
+// src/cli.ts
+var VERSION = "0.1.0";
+var HELP = `flagrix \u2014 scan GitHub repos and profiles for malware before you clone
+
+Usage:
+  flagrix scan <url | owner/repo> [--ref <branch|sha>] [--json] [--token <pat>]
+  flagrix scan-user <username> [--json] [--token <pat>]
+  flagrix mcp                       start the MCP server (stdio) for agents
+
+Options:
+  --ref <ref>       branch, tag, or commit to scan (default: default branch)
+  --json            machine-readable output (automatic when stdout is piped)
+  --token <pat>     GitHub token (or FLAGRIX_GITHUB_TOKEN / GITHUB_TOKEN env)
+  -h, --help        show this help
+  -v, --version     show version
+
+Exit codes:
+  0  low risk        2  medium risk \u2014 review before proceeding
+  1  scan failed     3  high risk \u2014 do not clone
+
+The verdict is pinned to the scanned commit SHA (in the JSON output as
+"commitSha"). Scanning is fully local: the only network calls go to the
+GitHub/npm APIs and the public detection-rules repository. No telemetry.
+Docs: https://github.com/flagrix-io/flagrix-cli`;
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      ref: { type: "string" },
+      json: { type: "boolean" },
+      token: { type: "string" },
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" }
+    }
+  });
+  if (values.version) {
+    console.log(VERSION);
+    return EXIT.LOW;
+  }
+  const [command, target] = positionals;
+  if (values.help || !command) {
+    console.log(HELP);
+    return values.help ? EXIT.LOW : EXIT.ERROR;
+  }
+  switch (command) {
+    case "scan":
+      if (!target) {
+        console.error("flagrix: scan requires a repository URL or owner/repo\n");
+        console.error(HELP);
+        return EXIT.ERROR;
+      }
+      return runScan(target, { ref: values.ref, json: values.json, token: values.token });
+    case "scan-user":
+      if (!target) {
+        console.error("flagrix: scan-user requires a GitHub username\n");
+        console.error(HELP);
+        return EXIT.ERROR;
+      }
+      return runScanUser(target, { json: values.json, token: values.token });
+    case "mcp": {
+      const { runMcp } = await import("./mcp-S44QVYNH.js");
+      return runMcp();
+    }
+    default:
+      console.error(`flagrix: unknown command "${command}"
+`);
+      console.error(HELP);
+      return EXIT.ERROR;
+  }
+}
+main().then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (error) => {
+    console.error(`flagrix: ${error.message}`);
+    process.exitCode = EXIT.ERROR;
+  }
+);

package/dist/mcp-S44QVYNH.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import {
+  describeSource,
+  loadSignatures,
+  parseRepoTarget,
+  resolveToken,
+  scanGitHubRepo,
+  scanGitHubUser,
+  securityScore
+} from "./chunk-FJUDM3F7.js";
+
+// src/commands/mcp.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+var GUIDANCE = {
+  low: "LOW risk: no blocking findings. Standard caution still applies.",
+  medium: "MEDIUM risk: do NOT clone, install, or execute this code until a human has reviewed the findings.",
+  high: "HIGH risk: do NOT clone, install, or execute this code. Treat the repository as malicious."
+};
+async function runMcp() {
+  const server = new McpServer({ name: "flagrix", version: "0.1.0" });
+  server.registerTool(
+    "scan_github_repo",
+    {
+      title: "Scan a GitHub repository for malware",
+      description: "Scans a GitHub repository for malicious patterns (backdoors, data exfiltration, supply-chain attacks, known-bad packages) BEFORE cloning or installing it. The verdict is pinned to the repository's current commit SHA. Call this before cloning any untrusted repository.",
+      inputSchema: {
+        target: z.string().describe("GitHub repository URL or owner/repo slug, e.g. https://github.com/acme/repo"),
+        ref: z.string().optional().describe("Branch, tag, or commit to scan (default: default branch)")
+      }
+    },
+    async ({ target, ref }) => {
+      const repo = parseRepoTarget(target, ref);
+      const loaded = await loadSignatures();
+      const result = await scanGitHubRepo(repo, {
+        signatures: loaded.signatures,
+        githubToken: resolveToken()
+      });
+      const note = describeSource(loaded);
+      const summary = [
+        `${result.riskLevel.toUpperCase()} risk \u2014 security score ${securityScore(result.riskScore)}/100 (verdict pinned to commit ${result.commitSha ?? "unknown"}).`,
+        GUIDANCE[result.riskLevel],
+        ...note ? [`Note: ${note}.`] : []
+      ].join(" ");
+      return {
+        content: [
+          { type: "text", text: summary },
+          { type: "text", text: JSON.stringify(result, null, 2) }
+        ],
+        isError: false
+      };
+    }
+  );
+  server.registerTool(
+    "scan_github_user",
+    {
+      title: "Scan a GitHub user profile for scam signals",
+      description: "Scores a GitHub user profile for throwaway-account and scam signals (account age, followers, activity, repository authenticity). Useful for vetting a 'recruiter' or 'client' before engaging with their repositories.",
+      inputSchema: {
+        username: z.string().describe("GitHub username or profile URL")
+      }
+    },
+    async ({ username }) => {
+      const login = username.trim().replace(/^https?:\/\/(www\.)?github\.com\//, "").replace(/\/.*$/, "");
+      const loaded = await loadSignatures();
+      const result = await scanGitHubUser(login, {
+        githubToken: resolveToken(),
+        userProfileRules: loaded.signatures.userProfileRules
+      });
+      const summary = `${result.riskLevel.toUpperCase()} risk profile \u2014 security score ${securityScore(result.riskScore)}/100. ${result.recommendation}`;
+      return {
+        content: [
+          { type: "text", text: summary },
+          { type: "text", text: JSON.stringify(result, null, 2) }
+        ],
+        isError: false
+      };
+    }
+  );
+  await server.connect(new StdioServerTransport());
+  await new Promise(() => {
+  });
+  return 0;
+}
+export {
+  runMcp
+};

package/docs/agent-gating.md

@@ -0,0 +1,71 @@
+# Gating agents with Flagrix
+
+Two ways to put Flagrix between an AI agent and untrusted code: the **MCP server**
+(the agent decides to scan, or is instructed to) and the **Claude Code hook**
+(every `git clone` is gated, no cooperation needed).
+
+## Exit codes (the contract)
+
+| code | meaning |
+|---|---|
+| 0 | low risk |
+| 1 | scan failed (network, auth, bad target) |
+| 2 | medium risk — review before proceeding |
+| 3 | high risk — do not clone |
+
+`--json` (or any piped stdout) emits the full scan result, including `commitSha` —
+the verdict applies to that commit, not to whatever the branch points at later.
+
+## MCP server
+
+```bash
+claude mcp add flagrix -- npx -y flagrix mcp
+```
+
+Tools exposed: `scan_github_repo {target, ref?}` and `scan_github_user {username}`.
+Set `GITHUB_TOKEN` in the environment to raise rate limits / scan private repos.
+
+Suggested agent instruction (CLAUDE.md or system prompt):
+
+> Before cloning or installing any repository you did not author, call the
+> `scan_github_repo` tool and follow its guidance. Do not proceed on MEDIUM or
+> HIGH verdicts without explicit human approval.
+
+## Claude Code clone gate (hook)
+
+Copies of the hook script ship inside the npm package (`hooks/flagrix-clone-gate.sh`).
+
+`~/.claude/settings.json` (or a project's `.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$(npm root -g)/flagrix/hooks/flagrix-clone-gate.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Install the package globally first (`npm i -g flagrix`), or vendor the script into
+your repo and point the hook at it. The hook only reacts to `git clone` /
+`gh repo clone` commands targeting github.com; everything else passes through.
+
+## CI
+
+```yaml
+- name: Gate on Flagrix scan
+  run: npx -y flagrix scan ${{ github.event.pull_request.head.repo.html_url }}
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+A non-zero exit fails the job (2/3 = risk verdicts, 1 = scan error).

package/hooks/flagrix-clone-gate.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Flagrix clone gate — Claude Code PreToolUse hook for the Bash tool.
+#
+# Scans any GitHub repo about to be cloned; blocks the clone (hook exit 2)
+# when Flagrix rates it MEDIUM or HIGH risk. See docs/agent-gating.md for the
+# settings.json wiring.
+set -euo pipefail
+
+payload="$(cat)"
+
+# Extract a github.com repo URL from a `git clone`/`gh repo clone` command.
+url="$(node -e '
+  let input = ""
+  process.stdin.on("data", (d) => (input += d))
+  process.stdin.on("end", () => {
+    try {
+      const cmd = JSON.parse(input)?.tool_input?.command ?? ""
+      if (!/\b(git\s+clone|gh\s+repo\s+clone)\b/.test(cmd)) return
+      const m =
+        cmd.match(/https?:\/\/github\.com\/[\w.-]+\/[\w.-]+/) ||
+        cmd.match(/git@github\.com:[\w.-]+\/[\w.-]+/) ||
+        cmd.match(/\bclone\s+([\w.-]+\/[\w.-]+)(?:\s|$)/)?.slice(1)
+      if (m) process.stdout.write(String(Array.isArray(m) ? m[0] : m))
+    } catch {}
+  })
+' <<< "$payload")"
+
+# Not a GitHub clone — allow.
+[ -z "$url" ] && exit 0
+
+if npx -y flagrix scan "$url" --json > /dev/null 2>&1; then
+  exit 0 # low risk
+else
+  code=$?
+  case "$code" in
+    2) echo "Flagrix: MEDIUM risk — review https://github.com/flagrix-io/flagrix-cli#exit-codes before cloning $url" >&2 ;;
+    3) echo "Flagrix: HIGH risk — do NOT clone $url (malicious patterns detected). Run: npx flagrix scan $url" >&2 ;;
+    *) echo "Flagrix: scan of $url failed (exit $code) — blocking out of caution. Run: npx flagrix scan $url" >&2 ;;
+  esac
+  exit 2 # exit 2 = block the tool call in Claude Code
+fi

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "flagrix",
+  "version": "0.1.0",
+  "description": "Scan GitHub repos and profiles for malware before you clone — CLI and MCP server for the Flagrix scanner",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "flagrix": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "hooks",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "security",
+    "malware-detection",
+    "supply-chain-security",
+    "scam-detection",
+    "github",
+    "scanner",
+    "cli",
+    "mcp",
+    "mcp-server"
+  ],
+  "homepage": "https://flagrix.io",
+  "mcpName": "io.github.flagrix-io/flagrix",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flagrix-io/flagrix-cli.git"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "sync-signatures": "node scripts/sync-signatures.mjs",
+    "prepublishOnly": "npm run sync-signatures && npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@flagrix/scanner-core": "github:flagrix-io/flagrix-scanner-core",
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.6.0"
+  }
+}