chainlink-audit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chainlink-integration-audit-kit contributors
+
+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,16 @@
+# chainlink-audit
+
+Security CLI for detecting potential Chainlink integration risks in Solidity repositories.
+
+```bash
+npm install -g chainlink-audit
+chainlink-audit init
+chainlink-audit scan .
+chainlink-audit scan . --format markdown --out chainlink-report.md
+chainlink-audit scan . --format html --out chainlink-report.html
+```
+
+Findings are heuristic leads for manual review, not confirmed vulnerabilities.
+
+See the repository README for full documentation:
+https://github.com/alva-p/chainlink-integration-audit-kit

package/dist/config.js

@@ -0,0 +1,77 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+export const configFileName = ".chainlink-audit.json";
+export const defaultConfig = {
+    exclude: ["test/", "tests/", "mock/", "mocks/", "script/", "lib/"],
+    format: "text",
+    minSeverity: "low",
+};
+export function severityRank(severity) {
+    return {
+        info: 0,
+        low: 1,
+        medium: 2,
+        high: 3,
+    }[severity];
+}
+export function parseOutputFormat(value) {
+    if (value === "text" || value === "json" || value === "markdown" || value === "html")
+        return value;
+    throw new Error(`Unsupported format "${value}". Use text, json, markdown, or html.`);
+}
+export function parseSeverity(value) {
+    if (value === "info" || value === "low" || value === "medium" || value === "high")
+        return value;
+    throw new Error(`Unsupported severity "${value}". Use info, low, medium, or high.`);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function normalizeConfig(raw) {
+    if (!isRecord(raw))
+        return { ...defaultConfig };
+    const exclude = Array.isArray(raw.exclude)
+        ? raw.exclude.filter((entry) => typeof entry === "string")
+        : defaultConfig.exclude;
+    const format = typeof raw.format === "string" ? parseOutputFormat(raw.format) : defaultConfig.format;
+    const minSeverity = typeof raw.minSeverity === "string" ? parseSeverity(raw.minSeverity) : defaultConfig.minSeverity;
+    return {
+        exclude,
+        format,
+        minSeverity,
+    };
+}
+export async function loadConfig(startPath = process.cwd()) {
+    const absoluteStart = path.resolve(startPath);
+    let current = absoluteStart;
+    try {
+        const stat = await fs.stat(current);
+        if (stat.isFile())
+            current = path.dirname(current);
+    }
+    catch {
+        current = process.cwd();
+    }
+    while (true) {
+        const candidate = path.join(current, configFileName);
+        try {
+            const raw = await fs.readFile(candidate, "utf8");
+            return normalizeConfig(JSON.parse(raw));
+        }
+        catch (error) {
+            const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+            if (code !== "ENOENT") {
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(`Failed to read ${candidate}: ${message}`);
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return { ...defaultConfig };
+        current = parent;
+    }
+}
+export async function writeDefaultConfig(targetPath = configFileName) {
+    const output = `${JSON.stringify(defaultConfig, null, 2)}\n`;
+    await fs.writeFile(targetPath, output, { encoding: "utf8", flag: "wx" });
+}

package/dist/index.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { promises as fs } from "node:fs";
+import { Command } from "commander";
+import { configFileName, loadConfig, parseOutputFormat, parseSeverity, writeDefaultConfig, } from "./config.js";
+import { renderJson } from "./reporters/json.js";
+import { renderHtml } from "./reporters/html.js";
+import { renderMarkdown } from "./reporters/markdown.js";
+import { renderText } from "./reporters/text.js";
+import { rules } from "./rules/index.js";
+import { scanPath } from "./scanner.js";
+const version = "0.1.0";
+function render(format, result) {
+    if (format === "json")
+        return renderJson(result);
+    if (format === "markdown")
+        return renderMarkdown(result);
+    if (format === "html")
+        return renderHtml(result);
+    return renderText(result);
+}
+const program = new Command();
+program
+    .name("chainlink-audit")
+    .description("CLI-first scanner for potential Chainlink integration risks in Solidity repositories.")
+    .version(version);
+program
+    .command("scan")
+    .argument("<path>", "Solidity file or repository path to scan")
+    .option("--format <format>", "Output format: text, json, markdown, html")
+    .option("--min-severity <severity>", "Minimum severity: info, low, medium, high")
+    .option("--out <file>", "Write report to a file instead of stdout")
+    .action(async (targetPath, options) => {
+    try {
+        const config = await loadConfig(targetPath);
+        if (options.format)
+            config.format = parseOutputFormat(options.format);
+        if (options.minSeverity)
+            config.minSeverity = parseSeverity(options.minSeverity);
+        const format = config.format;
+        const result = await scanPath(targetPath, { config });
+        const output = render(format, result);
+        if (options.out) {
+            await fs.writeFile(options.out, `${output}\n`, "utf8");
+        }
+        else {
+            console.log(output);
+        }
+        process.exitCode = 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`chainlink-audit: ${message}`);
+        process.exitCode = 2;
+    }
+});
+program.command("init").description(`Create ${configFileName} with recommended defaults`).action(async () => {
+    try {
+        await writeDefaultConfig();
+        console.log(`Created ${configFileName}`);
+    }
+    catch (error) {
+        const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+        if (code === "EEXIST") {
+            console.error(`chainlink-audit: ${configFileName} already exists`);
+            process.exitCode = 1;
+            return;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`chainlink-audit: ${message}`);
+        process.exitCode = 2;
+    }
+});
+program.command("rules").description("List available MVP rules").action(() => {
+    for (const rule of rules) {
+        const metadata = rule.metadata;
+        console.log(`${metadata.ruleId} [${metadata.severity}] ${metadata.product} - ${metadata.title}`);
+    }
+});
+program.command("version").description("Print CLI version").action(() => {
+    console.log(version);
+});
+program.parseAsync();

package/dist/reporters/html.js

@@ -0,0 +1,372 @@
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+function severityClass(severity) {
+    return `severity-${severity}`;
+}
+function findingCard(finding) {
+    return `
+      <article class="finding ${severityClass(finding.severity)}">
+        <header class="finding-header">
+          <div>
+            <p class="rule-id">${escapeHtml(finding.ruleId)}</p>
+            <h3>${escapeHtml(finding.title)}</h3>
+          </div>
+          <div class="badges">
+            <span class="badge severity">${escapeHtml(finding.severity)}</span>
+            <span class="badge confidence">${escapeHtml(finding.confidence)} confidence</span>
+          </div>
+        </header>
+        <dl class="meta">
+          <div><dt>Location</dt><dd>${escapeHtml(finding.file)}:${finding.line}</dd></div>
+          <div><dt>Manual Review</dt><dd>${finding.manualReviewRequired ? "Required" : "Optional"}</dd></div>
+        </dl>
+        <section>
+          <h4>Description</h4>
+          <p>${escapeHtml(finding.description)}</p>
+        </section>
+        <section>
+          <h4>Risk</h4>
+          <p>${escapeHtml(finding.risk)}</p>
+        </section>
+        <section>
+          <h4>Recommendation</h4>
+          <p>${escapeHtml(finding.recommendation)}</p>
+        </section>
+      </article>`;
+}
+export function renderHtml(result) {
+    const products = result.products.length > 0 ? result.products.join(", ") : "none detected";
+    const excludedPaths = result.config.exclude.length > 0 ? result.config.exclude.join(", ") : "none";
+    const generatedAt = new Date().toISOString();
+    const findings = result.findings.length > 0
+        ? result.findings.map(findingCard).join("\n")
+        : '<section class="empty">No potential Chainlink integration issues found by MVP rules. Manual review still required.</section>';
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Chainlink Integration Audit Report</title>
+  <script>
+    (function () {
+      var storedTheme = localStorage.getItem("chainlink-audit-theme");
+      var systemDark = window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches;
+      document.documentElement.dataset.theme = storedTheme || (systemDark ? "dark" : "light");
+    })();
+  </script>
+  <style>
+    :root {
+      color-scheme: light dark;
+      --bg: #f7f9fc;
+      --panel: #ffffff;
+      --panel-strong: #f8fafc;
+      --text: #111827;
+      --muted: #5b6472;
+      --border: #d8dee9;
+      --high: #b42318;
+      --medium: #b54708;
+      --low: #175cd3;
+      --info: #475467;
+      --accent: #0f5fff;
+      --accent-soft: #eef4ff;
+      --accent-border: #c7d7fe;
+      --accent-text: #253b74;
+      --shadow: 0 1px 2px rgb(16 24 40 / 4%);
+    }
+    :root[data-theme="dark"] {
+      --bg: #0f1115;
+      --panel: #171a21;
+      --panel-strong: #20242d;
+      --text: #eef2f7;
+      --muted: #a7b0bf;
+      --border: #303642;
+      --high: #ff8a80;
+      --medium: #ffbf66;
+      --low: #70b8ff;
+      --info: #c4cad4;
+      --accent: #72a7ff;
+      --accent-soft: #172033;
+      --accent-border: #2f4975;
+      --accent-text: #c9d8ff;
+      --shadow: 0 14px 32px rgb(0 0 0 / 22%);
+    }
+    @media (prefers-color-scheme: dark) {
+      :root:not([data-theme="light"]) {
+        --bg: #0f1115;
+        --panel: #171a21;
+        --panel-strong: #20242d;
+        --text: #eef2f7;
+        --muted: #a7b0bf;
+        --border: #303642;
+        --high: #ff8a80;
+        --medium: #ffbf66;
+        --low: #70b8ff;
+        --info: #c4cad4;
+        --accent: #72a7ff;
+        --accent-soft: #172033;
+        --accent-border: #2f4975;
+        --accent-text: #c9d8ff;
+        --shadow: 0 14px 32px rgb(0 0 0 / 22%);
+      }
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      background: var(--bg);
+      color: var(--text);
+      font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      line-height: 1.5;
+    }
+    .topbar {
+      align-items: center;
+      display: flex;
+      gap: 16px;
+      justify-content: space-between;
+      margin-bottom: 22px;
+    }
+    .brand {
+      color: var(--muted);
+      font-size: 13px;
+      font-weight: 700;
+      text-transform: uppercase;
+    }
+    .theme-toggle {
+      appearance: none;
+      background: var(--panel);
+      border: 1px solid var(--border);
+      border-radius: 999px;
+      color: var(--text);
+      cursor: pointer;
+      font: inherit;
+      font-size: 13px;
+      font-weight: 700;
+      padding: 8px 12px;
+      transition: background 140ms ease, border-color 140ms ease, color 140ms ease;
+    }
+    .theme-toggle:hover {
+      border-color: var(--accent);
+      color: var(--accent);
+    }
+    .theme-toggle:focus-visible {
+      outline: 3px solid var(--accent-border);
+      outline-offset: 2px;
+    }
+    main {
+      width: min(1120px, calc(100% - 32px));
+      margin: 0 auto;
+      padding: 40px 0 56px;
+    }
+    .hero {
+      padding-bottom: 24px;
+      border-bottom: 1px solid var(--border);
+      margin-bottom: 24px;
+    }
+    .eyebrow {
+      color: var(--accent);
+      font-size: 13px;
+      font-weight: 700;
+      letter-spacing: 0;
+      margin: 0 0 8px;
+      text-transform: uppercase;
+    }
+    h1 {
+      font-size: 34px;
+      line-height: 1.15;
+      margin: 0 0 12px;
+    }
+    .subtitle {
+      max-width: 800px;
+      color: var(--muted);
+      margin: 0;
+      font-size: 16px;
+    }
+    .summary {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+      gap: 12px;
+      margin: 24px 0;
+    }
+    .summary-card, .finding, .empty {
+      background: var(--panel);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      box-shadow: var(--shadow);
+    }
+    .summary-card {
+      padding: 16px;
+      min-height: 96px;
+    }
+    .summary-card span {
+      color: var(--muted);
+      display: block;
+      font-size: 13px;
+      margin-bottom: 6px;
+    }
+    .summary-card strong {
+      display: block;
+      font-size: 18px;
+      overflow-wrap: anywhere;
+    }
+    .note {
+      background: var(--accent-soft);
+      border: 1px solid var(--accent-border);
+      border-radius: 8px;
+      color: var(--accent-text);
+      margin: 0 0 24px;
+      padding: 14px 16px;
+    }
+    .findings {
+      display: grid;
+      gap: 16px;
+    }
+    .finding {
+      border-left: 5px solid var(--info);
+      padding: 18px;
+    }
+    .finding.severity-high { border-left-color: var(--high); }
+    .finding.severity-medium { border-left-color: var(--medium); }
+    .finding.severity-low { border-left-color: var(--low); }
+    .finding-header {
+      align-items: flex-start;
+      display: flex;
+      gap: 16px;
+      justify-content: space-between;
+      margin-bottom: 12px;
+    }
+    .rule-id {
+      color: var(--muted);
+      font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+      font-size: 13px;
+      font-weight: 700;
+      margin: 0 0 4px;
+    }
+    h2 { font-size: 22px; margin: 28px 0 14px; }
+    h3 { font-size: 18px; line-height: 1.3; margin: 0; }
+    h4 { font-size: 13px; margin: 16px 0 4px; text-transform: uppercase; }
+    p { margin: 0; }
+    .badges {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 8px;
+      justify-content: flex-end;
+    }
+    .badge {
+      border-radius: 999px;
+      border: 1px solid var(--border);
+      color: var(--muted);
+      font-size: 12px;
+      font-weight: 700;
+      padding: 4px 9px;
+      text-transform: uppercase;
+      white-space: nowrap;
+    }
+    .severity-high .badge.severity { border-color: #fecdca; color: var(--high); }
+    .severity-medium .badge.severity { border-color: #fedf89; color: var(--medium); }
+    .severity-low .badge.severity { border-color: #b2ddff; color: var(--low); }
+    :root[data-theme="dark"] .severity-high .badge.severity { border-color: #6f2b2b; }
+    :root[data-theme="dark"] .severity-medium .badge.severity { border-color: #694614; }
+    :root[data-theme="dark"] .severity-low .badge.severity { border-color: #254c7a; }
+    .meta {
+      display: grid;
+      gap: 10px;
+      grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+      margin: 12px 0 4px;
+    }
+    .meta div {
+      background: var(--panel-strong);
+      border-radius: 6px;
+      padding: 10px;
+    }
+    dt {
+      color: var(--muted);
+      font-size: 12px;
+      font-weight: 700;
+      margin-bottom: 3px;
+      text-transform: uppercase;
+    }
+    dd {
+      font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+      font-size: 13px;
+      margin: 0;
+      overflow-wrap: anywhere;
+    }
+    .empty { color: var(--muted); padding: 18px; }
+    footer {
+      color: var(--muted);
+      font-size: 12px;
+      margin-top: 28px;
+    }
+    @media (max-width: 640px) {
+      main { width: min(100% - 20px, 1120px); padding-top: 24px; }
+      h1 { font-size: 28px; }
+      .topbar { align-items: flex-start; }
+      .finding-header { display: block; }
+      .badges { justify-content: flex-start; margin-top: 12px; }
+    }
+    @media print {
+      .theme-toggle { display: none; }
+      body { background: #ffffff; color: #111827; }
+      .summary-card, .finding, .empty { box-shadow: none; }
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <div class="topbar">
+      <div class="brand">chainlink-audit</div>
+      <button class="theme-toggle" type="button" aria-label="Toggle dark mode">Theme: <span id="theme-label">System</span></button>
+    </div>
+    <header class="hero">
+      <p class="eyebrow">Chainlink Audit Kit</p>
+      <h1>Chainlink Integration Audit Report</h1>
+      <p class="subtitle">Potential Chainlink integration risks detected by heuristic MVP rules. Findings require manual review and are not confirmed vulnerabilities.</p>
+    </header>
+
+    <section class="summary" aria-label="Scan summary">
+      <div class="summary-card"><span>Target</span><strong>${escapeHtml(result.targetPath)}</strong></div>
+      <div class="summary-card"><span>Solidity Files</span><strong>${result.scannedFiles}</strong></div>
+      <div class="summary-card"><span>Products</span><strong>${escapeHtml(products)}</strong></div>
+      <div class="summary-card"><span>Findings</span><strong>${result.findings.length}</strong></div>
+      <div class="summary-card"><span>Minimum Severity</span><strong>${escapeHtml(result.config.minSeverity)}</strong></div>
+      <div class="summary-card"><span>Excluded Paths</span><strong>${escapeHtml(excludedPaths)}</strong></div>
+    </section>
+
+    <p class="note">This report is designed for audit triage. Validate each lead against source code, deployment configuration, and protocol assumptions before disclosure or remediation.</p>
+
+    <section>
+      <h2>Findings</h2>
+      <div class="findings">
+${findings}
+      </div>
+    </section>
+
+    <footer>Generated at ${escapeHtml(generatedAt)} by chainlink-audit.</footer>
+  </main>
+  <script>
+    (function () {
+      var button = document.querySelector(".theme-toggle");
+      var label = document.getElementById("theme-label");
+      function applyLabel() {
+        var theme = document.documentElement.dataset.theme || "light";
+        if (label) label.textContent = theme === "dark" ? "Dark" : "Light";
+      }
+      if (button) {
+        button.addEventListener("click", function () {
+          var nextTheme = document.documentElement.dataset.theme === "dark" ? "light" : "dark";
+          document.documentElement.dataset.theme = nextTheme;
+          localStorage.setItem("chainlink-audit-theme", nextTheme);
+          applyLabel();
+        });
+      }
+      applyLabel();
+    })();
+  </script>
+</body>
+</html>`;
+}

package/dist/reporters/json.js

@@ -0,0 +1,3 @@
+export function renderJson(result) {
+    return JSON.stringify(result, null, 2);
+}

package/dist/reporters/markdown.js

@@ -0,0 +1,27 @@
+export function renderMarkdown(result) {
+    const products = result.products.length > 0 ? result.products.join(", ") : "none detected";
+    const lines = [
+        "# Chainlink Integration Audit Report",
+        "",
+        "## Summary",
+        "",
+        `- Target: \`${result.targetPath}\``,
+        `- Solidity files scanned: ${result.scannedFiles}`,
+        `- Detected Chainlink products: ${products}`,
+        `- Minimum severity: ${result.config.minSeverity}`,
+        `- Excluded paths: ${result.config.exclude.length > 0 ? result.config.exclude.join(", ") : "none"}`,
+        `- Findings: ${result.findings.length}`,
+        "",
+        "This report contains potential issues produced by heuristic MVP rules. Findings require manual review before disclosure or remediation.",
+        "",
+    ];
+    if (result.findings.length === 0) {
+        lines.push("## Findings", "", "No potential Chainlink integration issues found by MVP rules.");
+        return lines.join("\n");
+    }
+    lines.push("## Findings", "");
+    for (const finding of result.findings) {
+        lines.push(`### ${finding.ruleId}: ${finding.title}`, "", `- Severity: ${finding.severity}`, `- Confidence: ${finding.confidence}`, `- Location: \`${finding.file}:${finding.line}\``, `- Manual review required: ${finding.manualReviewRequired ? "yes" : "no"}`, "", "#### Description", "", finding.description, "", "#### Risk", "", finding.risk, "", "#### Recommendation", "", finding.recommendation, "");
+    }
+    return lines.join("\n");
+}

package/dist/reporters/text.js

@@ -0,0 +1,27 @@
+export function renderText(result) {
+    const products = result.products.length > 0 ? result.products.join(", ") : "none detected";
+    const header = [
+        "Chainlink Integration Audit Kit",
+        `Target: ${result.targetPath}`,
+        `Solidity files scanned: ${result.scannedFiles}`,
+        `Detected Chainlink products: ${products}`,
+        `Minimum severity: ${result.config.minSeverity}`,
+        `Excluded paths: ${result.config.exclude.length > 0 ? result.config.exclude.join(", ") : "none"}`,
+        `Findings: ${result.findings.length}`,
+    ].join("\n");
+    if (result.findings.length === 0) {
+        return `${header}\n\nNo potential Chainlink integration issues found by MVP rules. Manual review still required.`;
+    }
+    const findings = result.findings
+        .map((finding) => [
+        `[${finding.severity.toUpperCase()}] ${finding.ruleId} - ${finding.title}`,
+        `  Confidence: ${finding.confidence}`,
+        `  Location: ${finding.file}:${finding.line}`,
+        `  Description: ${finding.description}`,
+        `  Risk: ${finding.risk}`,
+        `  Recommendation: ${finding.recommendation}`,
+        `  Manual review required: ${finding.manualReviewRequired ? "yes" : "no"}`,
+    ].join("\n"))
+        .join("\n\n");
+    return `${header}\n\n${findings}`;
+}