@flagrix/scanner-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Flagrix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# @flagrix/scanner-core
+
+Open-source scanning engine behind [Flagrix](https://flagrix.io) — detects malware, backdoors, and supply-chain attacks in GitHub repositories and GitHub profiles.
+
+Built after real-world fake-recruiter campaigns ("coding assignment" repos that steal wallets, SSH keys, and browser sessions) started targeting developers. Flagrix scans before you clone.
+
+## What it detects
+
+- Known malicious npm packages (active campaign IOCs, typosquats)
+- Obfuscated JavaScript (hex arrays, eval chains, base64 droppers)
+- Supply-chain attacks (dependency confusion, install-time scripts)
+- Backdoors, reverse shells, and data-exfiltration patterns
+- Crypto miners and credential/wallet stealers
+- Suspicious install hooks (postinstall, curl-pipe-bash)
+- Social-engineering markers and repository anomalies
+
+Signature data lives in the sibling repo [flagrix-detection-rules](https://github.com/flagrix-io/flagrix-detection-rules).
+
+## Usage
+
+```ts
+import { scanGitHubRepo, type SignatureDatabase } from "@flagrix/scanner-core"
+
+const result = await scanGitHubRepo(
+  { owner: "some-org", repo: "some-repo", branch: "main", url: "https://github.com/some-org/some-repo" },
+  { signatures, githubToken } // token optional — raises rate limits, enables private repos
+)
+
+console.log(result.riskLevel) // "low" | "medium" | "high"
+console.log(result.findings)  // detailed findings with severity + evidence
+console.log(result.commitSha) // the exact commit the verdict applies to
+```
+
+Scans are pinned: the branch is resolved to a commit SHA up front and every file is read at that SHA, so a push mid-scan (or between scan and clone) can't invalidate the verdict silently — compare `commitSha` against the head you actually check out.
+
+Also exported: `scanGitHubUser` (profile authenticity scoring) and the shared risk-calculation utilities. See [src/index.ts](src/index.ts) for the full API.
+
+The package also ships standalone `scoreLinkedInProfile` and `scanPdfBytes` / `scanPdfFromUrl` scanners. These aren't wired into the current Flagrix extension (which is GitHub-only) or backed by rules in flagrix-detection-rules — they're available for anyone building on the library, but should be treated as unmaintained until that changes.
+
+## GitHub API rate limits
+
+`scanGitHubRepo` and `scanGitHubUser` call the GitHub REST API directly. A single repo scan issues one tree request plus up to ~50 file-content requests. Unauthenticated, GitHub allows **60 requests/hour** — enough for a handful of scans. Pass a `githubToken` (a fine-grained or classic PAT, `public_repo`/`repo` scope) in the options to raise this to **5,000 requests/hour** and to scan private repositories:
+
+```ts
+await scanGitHubRepo(repo, { signatures, githubToken })
+```
+
+## Risk scoring
+
+Findings are weighted by severity (`critical` 0.4, `high` 0.25, `medium` 0.15, `low` 0.05, `info` 0.01), summed, and capped at 1.0. `getRiskLevel` maps the score to a level using the shared `RISK_THRESHOLDS` (`< 0.3` low, `< 0.6` medium, otherwise high) — with one override: a single `critical` finding always forces `high`, since a lone backdoor or keylogger shouldn't average down to "review before cloning" just because nothing else in the repo was flagged. Pass `findings` as the scanner does (`getRiskLevel(score, findings)`) to get this floor; omit it to fall back to threshold-only scoring. The GitHub **user** scanner uses its own tuned thresholds because profile signals (account age, follower ratios) distribute differently from code findings.
+
+## Development
+
+```bash
+npm install
+npm run build   # tsc → dist/
+npm test        # vitest
+```
+
+Pure TypeScript with a single runtime dependency (`franc-min` for language detection). Callers inject network and storage — the primary consumer is the Flagrix Chrome extension, which currently uses the GitHub repo and profile scanners and supplies `fetch` results and signature data. See [CONTRIBUTING.md](CONTRIBUTING.md) to add a detector or report a false positive.
+
+## Disclaimer
+
+Risk assessments are informational, not definitive malware or fraud determinations. Always verify through official channels.
+
+## AI Disclosure
+
+This project leverages Claude AI for boilerplate generation, test-suite expansion, and optimization. All AI-generated code is strictly reviewed, refactored, and verified by human maintainers before merging.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+*Part of the [Flagrix](https://flagrix.io) open-core security platform.*

package/dist/github/api-error.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Turns a failed GitHub API response into an actionable error.
+ *
+ * GitHub uses 403 for several unrelated conditions (SAML/SSO enforcement,
+ * disabled classic PATs, rate limiting) and explains which one in the JSON
+ * body — so surface that instead of a bare status code.
+ */
+export declare function githubApiError(response: Response, fallback?: string): Promise<Error>;

package/dist/github/api-error.js

@@ -0,0 +1,36 @@
+/**
+ * Turns a failed GitHub API response into an actionable error.
+ *
+ * GitHub uses 403 for several unrelated conditions (SAML/SSO enforcement,
+ * disabled classic PATs, rate limiting) and explains which one in the JSON
+ * body — so surface that instead of a bare status code.
+ */
+export async function githubApiError(response, fallback = "GitHub API error") {
+    let apiMessage = "";
+    try {
+        const body = (await response.json());
+        if (typeof body?.message === "string")
+            apiMessage = body.message;
+    }
+    catch {
+        // Non-JSON body — fall through to the status-only message.
+    }
+    if (response.status === 401) {
+        return new Error("GitHub token is invalid or expired — update it in Flagrix settings (401).");
+    }
+    if (response.status === 403) {
+        if (/saml|sso/i.test(apiMessage) || response.headers?.get("x-github-sso")) {
+            return new Error("This organization requires SSO authorization for your token. Open github.com/settings/tokens and use 'Configure SSO' on your token to authorize it for the organization (403).");
+        }
+        if (/personal access token/i.test(apiMessage)) {
+            return new Error(`This organization restricts personal access tokens — ${apiMessage} (403).`);
+        }
+        if (response.headers?.get("x-ratelimit-remaining") === "0") {
+            return new Error("GitHub API rate limit exceeded. Add a personal access token in Flagrix settings to raise the limit (403).");
+        }
+    }
+    return new Error(apiMessage
+        ? `${fallback}: ${response.status} — ${apiMessage}`
+        : `${fallback}: ${response.status}`);
+}
+//# sourceMappingURL=api-error.js.map

package/dist/github/api-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-error.js","sourceRoot":"","sources":["../../src/github/api-error.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,QAAkB,EAClB,QAAQ,GAAG,kBAAkB;IAE7B,IAAI,UAAU,GAAG,EAAE,CAAA;IACnB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA0B,CAAA;QAC7D,IAAI,OAAO,IAAI,EAAE,OAAO,KAAK,QAAQ;YAAE,UAAU,GAAG,IAAI,CAAC,OAAO,CAAA;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,2DAA2D;IAC7D,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QAC5B,OAAO,IAAI,KAAK,CACd,2EAA2E,CAC5E,CAAA;IACH,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QAC5B,IAAI,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC;YAC1E,OAAO,IAAI,KAAK,CACd,gLAAgL,CACjL,CAAA;QACH,CAAC;QACD,IAAI,wBAAwB,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YAC9C,OAAO,IAAI,KAAK,CACd,wDAAwD,UAAU,SAAS,CAC5E,CAAA;QACH,CAAC;QACD,IAAI,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,uBAAuB,CAAC,KAAK,GAAG,EAAE,CAAC;YAC3D,OAAO,IAAI,KAAK,CACd,2GAA2G,CAC5G,CAAA;QACH,CAAC;IACH,CAAC;IAED,OAAO,IAAI,KAAK,CACd,UAAU;QACR,CAAC,CAAC,GAAG,QAAQ,KAAK,QAAQ,CAAC,MAAM,MAAM,UAAU,EAAE;QACnD,CAAC,CAAC,GAAG,QAAQ,KAAK,QAAQ,CAAC,MAAM,EAAE,CACtC,CAAA;AACH,CAAC"}

package/dist/github/repo-scanner.d.ts

@@ -0,0 +1,15 @@
+/**
+ * GitHub Repository Scanner
+ *
+ * Scans GitHub repositories for malware signatures, obfuscated code,
+ * suspicious dependencies, and postinstall scripts.
+ *
+ * Uses GitHub API to fetch repo contents without full clone.
+ * No chrome.storage dependency — token and signatures are passed as options.
+ */
+import type { GitHubFinding, GitHubRepoInfo, GitHubScanResult, RepoScanOptions } from "../types/index.js";
+import { isTestFile } from "../rules/rule-matcher.js";
+export declare function scanGitHubRepo(repo: GitHubRepoInfo, options: RepoScanOptions): Promise<GitHubScanResult>;
+declare function detectObfuscation(content: string, filePath: string): GitHubFinding[];
+declare function checkTyposquat(packageName: string): string | null;
+export { checkTyposquat, detectObfuscation, isTestFile };