agent-security-lens 0.1.0

package/src/report/markdown.mjs

@@ -0,0 +1,145 @@
+export function renderMarkdown(result) {
+  const lines = [];
+  lines.push("# AgentSecurityLens Security Assessment");
+  lines.push("");
+  lines.push(`- Assessment ID: \`${result.assessment.id}\``);
+  lines.push(`- Target: \`${result.assessment.target_path}\``);
+  lines.push(`- Trust Score: **${result.summary.trust_score}/100**`);
+  lines.push(`- Findings: **${result.summary.total_findings}**`);
+  lines.push(`- Categories: ${Object.entries(result.summary.by_category).map(([key, value]) => `\`${key}\`: ${value}`).join(", ") || "none"}`);
+  lines.push(`- Profile Coverage Avg: **${result.summary.profile_coverage_average}**`);
+  lines.push("");
+  lines.push("## Profiles");
+  lines.push("");
+  for (const profile of result.profiles) {
+    lines.push(`- \`${profile.id}@${profile.version}\` (${profile.status}, confidence ${profile.confidence})`);
+  }
+  lines.push("");
+  lines.push("## Rule Packs");
+  lines.push("");
+  for (const pack of result.rule_packs) {
+    lines.push(`- \`${pack.id}@${pack.version}\` (${pack.rule_count} rules)`);
+  }
+  lines.push("");
+  if (result.recommendation_packs?.length) {
+    lines.push("## Recommendation Packs");
+    lines.push("");
+    for (const pack of result.recommendation_packs) {
+      lines.push(`- \`${pack.id}@${pack.version}\` (${pack.status}, ${pack.recommendation_count} recommendations)`);
+    }
+    lines.push("");
+  }
+  if (result.trust_signal_taxonomies?.length) {
+    lines.push("## Trust Signal Taxonomies");
+    lines.push("");
+    for (const taxonomy of result.trust_signal_taxonomies) {
+      lines.push(`- \`${taxonomy.id}@${taxonomy.version}\` (${taxonomy.status}, ${taxonomy.signal_count} signals)`);
+    }
+    lines.push("");
+  }
+  lines.push("## Profile Selection");
+  lines.push("");
+  lines.push(`- Mode: \`${result.lineage.profile_selection.mode}\``);
+  lines.push(`- Selected: \`${result.lineage.profile_selection.selected_profile}\``);
+  if (result.lineage.profile_selection.detection_signals.length) {
+    const signals = result.lineage.profile_selection.detection_signals
+      .map((signal) => `\`${signal.type}:${signal.value}\``)
+      .join(", ");
+    lines.push(`- Signals: ${signals}`);
+  }
+  lines.push("");
+
+  if (result.risk_domains?.length) {
+    lines.push("## Risk Domains");
+    lines.push("");
+    for (const domain of result.risk_domains) {
+      lines.push(`- **${domain.title}**: ${domain.count} finding(s), highest \`${domain.highest_severity}\``);
+    }
+    lines.push("");
+  }
+
+  if (result.trust_signals?.length) {
+    const summary = result.summary.trust_signal_summary;
+    lines.push("## Trust Signals");
+    lines.push("");
+    lines.push(`- Total: **${summary.total}**`);
+    lines.push(`- Net weight: **${summary.net_weight}**`);
+    lines.push(
+      `- Direction: ${Object.entries(summary.by_direction).map(([key, value]) => `\`${key}\`: ${value}`).join(", ")}`
+    );
+    lines.push("");
+    for (const signal of result.trust_signals.slice(0, 5)) {
+      lines.push(`- \`${signal.signal_id}\` ${signal.title} (${signal.weight}) at \`${signal.evidence.path}:${signal.evidence.line}\``);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Detailed Findings");
+  lines.push("");
+
+  if (result.findings.length === 0) {
+    lines.push("No risk findings detected by the current rule packs.");
+    lines.push("");
+    lines.push("> Known limitation: this does not prove the agent environment is safe.");
+    return lines.join("\n");
+  }
+
+  for (const finding of result.findings) {
+    lines.push(`### ${finding.title}`);
+    lines.push("");
+    lines.push(`- Severity: \`${finding.severity}\``);
+    lines.push(`- Category: \`${finding.category}\``);
+    lines.push(`- Permissions: ${finding.permissions.map((item) => `\`${item}\``).join(", ") || "none"}`);
+    lines.push(`- Evidence: \`${finding.evidence.path}:${finding.evidence.line}\``);
+    if (finding.evidence_items.length > 1) {
+      lines.push(`- Additional evidence: ${finding.evidence_items.length - 1} more match(es) in this file`);
+    }
+    lines.push("");
+    lines.push("**Why it matters**");
+    lines.push("");
+    lines.push(finding.why_it_matters);
+    lines.push("");
+    if (finding.recommended_actions.length) {
+      lines.push("**Recommended actions**");
+      lines.push("");
+      for (const action of finding.recommended_actions) lines.push(`- ${action}`);
+      lines.push("");
+    }
+    if (finding.recommended_alternatives.length) {
+      lines.push("**Recommended alternatives**");
+      lines.push("");
+      for (const alternative of finding.recommended_alternatives) lines.push(`- ${alternative}`);
+      lines.push("");
+    }
+    if (finding.migration_instruction) {
+      lines.push("**Copyable migration instruction**");
+      lines.push("");
+      lines.push("```txt");
+      lines.push(finding.migration_instruction);
+      lines.push("```");
+      lines.push("");
+    }
+    if (finding.recommendations?.length) {
+      const top = finding.recommendations[0];
+      lines.push("**Top recommendation**");
+      lines.push("");
+      lines.push(`- \`${top.id}\`: ${top.title}`);
+      lines.push(`- Type: \`${top.type}\`, confidence: \`${top.confidence}\``);
+      if (top.one_step_commands?.length) {
+        lines.push("");
+        lines.push("**One-step instruction**");
+        lines.push("");
+        lines.push("```txt");
+        lines.push(top.one_step_commands[0].command);
+        lines.push("```");
+      }
+      if (top.rollback_note) {
+        lines.push("");
+        lines.push(`Rollback note: ${top.rollback_note}`);
+      }
+      lines.push("");
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/results/compare-results.mjs

@@ -0,0 +1,106 @@
+import { readFile } from "node:fs/promises";
+
+function findingKey(finding) {
+  return [
+    finding.rule_id,
+    finding.evidence?.path || "unknown-path",
+    finding.evidence?.preview || finding.title
+  ].join("|");
+}
+
+function summarizeFinding(finding) {
+  return {
+    id: finding.id,
+    rule_id: finding.rule_id,
+    title: finding.title,
+    severity: finding.severity,
+    category: finding.category,
+    evidence: finding.evidence
+  };
+}
+
+function indexById(items) {
+  return new Map(items.map((item) => [item.id, item]));
+}
+
+function diffVersionedItems(previousItems, currentItems) {
+  const previous = indexById(previousItems);
+  const current = indexById(currentItems);
+  const added = [];
+  const removed = [];
+  const changed = [];
+
+  for (const [id, item] of current.entries()) {
+    const oldItem = previous.get(id);
+    if (!oldItem) {
+      added.push(item);
+    } else if (oldItem.version !== item.version) {
+      changed.push({ id, previous_version: oldItem.version, current_version: item.version });
+    }
+  }
+
+  for (const [id, item] of previous.entries()) {
+    if (!current.has(id)) removed.push(item);
+  }
+
+  return { added, removed, changed };
+}
+
+export function compareAssessmentResults(previous, current) {
+  const previousFindings = new Map(previous.findings.map((finding) => [findingKey(finding), finding]));
+  const currentFindings = new Map(current.findings.map((finding) => [findingKey(finding), finding]));
+  const added = [];
+  const resolved = [];
+  const persistent = [];
+
+  for (const [key, finding] of currentFindings.entries()) {
+    if (previousFindings.has(key)) {
+      persistent.push(summarizeFinding(finding));
+    } else {
+      added.push(summarizeFinding(finding));
+    }
+  }
+
+  for (const [key, finding] of previousFindings.entries()) {
+    if (!currentFindings.has(key)) {
+      resolved.push(summarizeFinding(finding));
+    }
+  }
+
+  return {
+    schema_version: "0.1.0",
+    comparison: {
+      previous_assessment_id: previous.assessment.id,
+      current_assessment_id: current.assessment.id,
+      previous_completed_at: previous.assessment.completed_at,
+      current_completed_at: current.assessment.completed_at,
+      compared_at: new Date().toISOString()
+    },
+    score: {
+      previous: previous.summary.trust_score,
+      current: current.summary.trust_score,
+      delta: current.summary.trust_score - previous.summary.trust_score
+    },
+    finding_counts: {
+      previous: previous.findings.length,
+      current: current.findings.length,
+      added: added.length,
+      resolved: resolved.length,
+      persistent: persistent.length
+    },
+    profiles: diffVersionedItems(previous.profiles, current.profiles),
+    rule_packs: diffVersionedItems(previous.rule_packs, current.rule_packs),
+    recommendation_packs: diffVersionedItems(previous.recommendation_packs || [], current.recommendation_packs || []),
+    findings: {
+      added,
+      resolved,
+      persistent
+    }
+  };
+}
+
+export async function compareAssessmentFiles(previousPath, currentPath) {
+  const previous = JSON.parse(await readFile(previousPath, "utf8"));
+  const current = JSON.parse(await readFile(currentPath, "utf8"));
+  return compareAssessmentResults(previous, current);
+}

package/src/results/save-result.mjs

@@ -0,0 +1,29 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+
+function safeTimestamp(value) {
+  return value.replace(/[:.]/g, "-");
+}
+
+function targetSlug(targetPath) {
+  return basename(targetPath).replace(/[^a-zA-Z0-9._-]+/g, "-") || "target";
+}
+
+export async function saveAssessmentResult({ result, outDir }) {
+  const baseDir = resolve(outDir || join(result.assessment.target_path, ".agentsecuritylens", "runs"));
+  await mkdir(baseDir, { recursive: true });
+
+  const fileName = [
+    safeTimestamp(result.assessment.started_at),
+    targetSlug(result.assessment.target_path),
+    result.assessment.id
+  ].join("__");
+  const outputPath = join(baseDir, `${fileName}.json`);
+
+  await writeFile(outputPath, `${JSON.stringify(result, null, 2)}\n`, "utf8");
+
+  return {
+    path: outputPath,
+    archived_at: new Date().toISOString()
+  };
+}

package/src/rules/load-rules.mjs

@@ -0,0 +1,22 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "..", "..");
+
+export async function loadRulePacks(profiles) {
+  const packIds = new Set();
+  for (const profile of profiles) {
+    for (const packId of profile.rule_packs || []) {
+      packIds.add(packId);
+    }
+  }
+
+  const packs = [];
+  for (const packId of packIds) {
+    const content = await readFile(join(ROOT, "rule-packs", packId, "rules.json"), "utf8");
+    packs.push(JSON.parse(content));
+  }
+  return packs;
+}

package/src/rules/match-rules.mjs

@@ -0,0 +1,99 @@
+import { readFile } from "node:fs/promises";
+
+function fileMatches(rule, relativePath) {
+  const targets = rule.target_paths || ["**/*"];
+  return targets.some((target) => {
+    if (target === "**/*") return true;
+    if (target.endsWith("/**")) return relativePath.startsWith(target.slice(0, -3));
+    if (target.startsWith("**/")) return relativePath.endsWith(target.slice(3));
+    if (target.includes("*")) {
+      const regex = new RegExp(`^${target.replaceAll(".", "\\.").replaceAll("**", ".*").replaceAll("*", "[^/]*")}$`);
+      return regex.test(relativePath);
+    }
+    return relativePath === target || relativePath.endsWith(`/${target}`);
+  });
+}
+
+function createFinding({ rule, file, line, lineNumber, profileIds }) {
+  return {
+    id: `${rule.id}:${file.relative_path}`,
+    rule_id: rule.id,
+    title: rule.title,
+    category: rule.category,
+    severity: rule.severity,
+    confidence: rule.confidence,
+    permissions: rule.permissions || [],
+    profile_ids: profileIds,
+    why_it_matters: rule.why_it_matters,
+    recommended_actions: rule.recommended_actions || [],
+    recommended_alternatives: rule.recommended_alternatives || [],
+    migration_instruction: rule.migration_instruction || "",
+    supersedes: rule.supersedes || [],
+    evidence: {
+      path: file.relative_path,
+      line: lineNumber,
+      preview: line.trim().slice(0, 240)
+    },
+    evidence_items: [
+      {
+        path: file.relative_path,
+        line: lineNumber,
+        preview: line.trim().slice(0, 240)
+      }
+    ]
+  };
+}
+
+function mergeFinding(existing, incoming) {
+  const seen = new Set(existing.evidence_items.map((item) => `${item.path}:${item.line}`));
+  for (const item of incoming.evidence_items) {
+    const key = `${item.path}:${item.line}`;
+    if (seen.has(key)) continue;
+    existing.evidence_items.push(item);
+    seen.add(key);
+  }
+  existing.evidence = existing.evidence_items[0];
+  return existing;
+}
+
+export async function matchRules({ files, profiles, rulePacks }) {
+  const findingsByKey = new Map();
+  const profileIds = profiles.map((profile) => profile.id);
+
+  for (const file of files) {
+    const content = await readFile(file.path, "utf8");
+    const lines = content.split(/\r?\n/);
+
+    for (const pack of rulePacks) {
+      for (const rule of pack.rules) {
+        if (!fileMatches(rule, file.relative_path)) continue;
+
+        const patterns = rule.patterns || [];
+        let matchedForFile = false;
+        for (let index = 0; index < lines.length; index += 1) {
+          const line = lines[index];
+          const matched = patterns.some((pattern) => new RegExp(pattern, "i").test(line));
+          if (!matched) continue;
+          const finding = createFinding({
+            rule,
+            file,
+            line,
+            lineNumber: index + 1,
+            profileIds
+          });
+          const key = `${finding.rule_id}:${finding.evidence.path}`;
+          if (findingsByKey.has(key)) {
+            mergeFinding(findingsByKey.get(key), finding);
+          } else {
+            findingsByKey.set(key, finding);
+          }
+          matchedForFile = true;
+          if (rule.match_scope === "file") break;
+        }
+        if (matchedForFile && rule.match_scope === "file") continue;
+      }
+    }
+  }
+
+  return Array.from(findingsByKey.values());
+}

package/src/rules/supersedes.mjs

@@ -0,0 +1,39 @@
+function evidenceOverlaps(a, b) {
+  const pathsA = new Set((a.evidence_items || [a.evidence]).map((item) => item.path));
+  const pathsB = new Set((b.evidence_items || [b.evidence]).map((item) => item.path));
+  for (const path of pathsA) {
+    if (pathsB.has(path)) return true;
+  }
+  return false;
+}
+
+function dedupeByRulePath(findings) {
+  const byKey = new Map();
+  for (const finding of findings) {
+    const key = `${finding.rule_id}:${finding.evidence.path}`;
+    if (!byKey.has(key)) {
+      byKey.set(key, finding);
+      continue;
+    }
+    const existing = byKey.get(key);
+    const seen = new Set((existing.evidence_items || [existing.evidence]).map((item) => `${item.path}:${item.preview}`));
+    for (const item of finding.evidence_items || [finding.evidence]) {
+      const itemKey = `${item.path}:${item.preview}`;
+      if (seen.has(itemKey)) continue;
+      existing.evidence_items.push(item);
+      seen.add(itemKey);
+    }
+  }
+  return Array.from(byKey.values());
+}
+
+export function applySupersedes(findings) {
+  const filtered = findings.filter((candidate) => {
+    return !findings.some((other) => {
+      if (other === candidate) return false;
+      if (!other.supersedes?.includes(candidate.rule_id)) return false;
+      return evidenceOverlaps(other, candidate);
+    });
+  });
+  return dedupeByRulePath(filtered);
+}

package/src/store/assessment-store.mjs

@@ -0,0 +1,78 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { compareAssessmentResults } from "../results/compare-results.mjs";
+
+const DEFAULT_STORE_DIR = join(process.cwd(), ".agentsecuritylens", "store", "assessments");
+
+function safeTimestamp(value) {
+  return value.replace(/[:.]/g, "-");
+}
+
+function targetSlug(targetPath) {
+  return basename(targetPath).replace(/[^a-zA-Z0-9._-]+/g, "-") || "target";
+}
+
+export function assessmentStoreDir() {
+  return resolve(process.env.ASL_STORE_DIR || DEFAULT_STORE_DIR);
+}
+
+function assessmentFileName(result) {
+  return [
+    safeTimestamp(result.assessment.started_at),
+    targetSlug(result.assessment.target_path),
+    result.assessment.id
+  ].join("__") + ".json";
+}
+
+function summaryFromResult(result, filePath) {
+  return {
+    id: result.assessment.id,
+    target_path: result.assessment.target_path,
+    completed_at: result.assessment.completed_at,
+    selected_profile: result.lineage.profile_selection.selected_profile,
+    trust_score: result.summary.trust_score,
+    total_findings: result.summary.total_findings,
+    trust_signals: result.trust_signals?.length || 0,
+    file_path: filePath
+  };
+}
+
+export async function saveToAssessmentStore(result) {
+  const dir = assessmentStoreDir();
+  await mkdir(dir, { recursive: true });
+  const filePath = join(dir, assessmentFileName(result));
+  await writeFile(filePath, `${JSON.stringify(result, null, 2)}\n`, "utf8");
+  return summaryFromResult(result, filePath);
+}
+
+export async function listAssessmentStore() {
+  const dir = assessmentStoreDir();
+  await mkdir(dir, { recursive: true });
+  const files = (await readdir(dir)).filter((file) => file.endsWith(".json"));
+  const items = [];
+
+  for (const file of files) {
+    const filePath = join(dir, file);
+    try {
+      const result = JSON.parse(await readFile(filePath, "utf8"));
+      items.push(summaryFromResult(result, filePath));
+    } catch {
+      continue;
+    }
+  }
+
+  return items.sort((left, right) => right.completed_at.localeCompare(left.completed_at));
+}
+
+export async function readAssessmentFromStore(id) {
+  const items = await listAssessmentStore();
+  const item = items.find((entry) => entry.id === id);
+  if (!item) throw new Error(`Assessment not found: ${id}`);
+  return JSON.parse(await readFile(item.file_path, "utf8"));
+}
+
+export async function compareStoredAssessments(previousId, currentId) {
+  const previous = await readAssessmentFromStore(previousId);
+  const current = await readAssessmentFromStore(currentId);
+  return compareAssessmentResults(previous, current);
+}

package/src/trust/derive-trust-signals.mjs

@@ -0,0 +1,73 @@
+function requiredPermissions(signal) {
+  return (signal.evidence_required || [])
+    .filter((item) => item.startsWith("permission:"))
+    .map((item) => item.slice("permission:".length));
+}
+
+function signalApplies(signal, finding) {
+  if (signal.source_type !== "static-analysis") return false;
+
+  const permissions = requiredPermissions(signal);
+  if (permissions.length && !permissions.some((permission) => finding.permissions.includes(permission))) return false;
+
+  return permissions.length > 0;
+}
+
+function signalEvidence(finding) {
+  return {
+    finding_id: finding.id,
+    rule_id: finding.rule_id,
+    path: finding.evidence.path,
+    line: finding.evidence.line,
+    preview: finding.evidence.preview
+  };
+}
+
+export function deriveTrustSignals({ findings, taxonomies }) {
+  const signals = taxonomies.flatMap((taxonomy) => taxonomy.signals || []);
+  const emitted = [];
+  const seen = new Set();
+
+  for (const finding of findings) {
+    for (const signal of signals) {
+      if (!signalApplies(signal, finding)) continue;
+
+      const key = `${signal.id}:${finding.id}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      emitted.push({
+        id: `${signal.id}:${finding.id}`,
+        signal_id: signal.id,
+        title: signal.title,
+        direction: signal.direction,
+        weight: signal.weight,
+        source_type: signal.source_type,
+        applies_to: signal.applies_to,
+        description: signal.description,
+        evidence: signalEvidence(finding)
+      });
+    }
+  }
+
+  return emitted;
+}
+
+export function summarizeTrustSignals(signals) {
+  const byDirection = {};
+  const bySource = {};
+  let netWeight = 0;
+
+  for (const signal of signals) {
+    byDirection[signal.direction] = (byDirection[signal.direction] || 0) + 1;
+    bySource[signal.source_type] = (bySource[signal.source_type] || 0) + 1;
+    netWeight += signal.weight;
+  }
+
+  return {
+    total: signals.length,
+    by_direction: byDirection,
+    by_source: bySource,
+    net_weight: netWeight
+  };
+}

package/src/trust/load-trust-signals.mjs

@@ -0,0 +1,17 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "..", "..");
+
+const TRUST_SIGNAL_FILES = ["data/trust/signal-taxonomy.json"];
+
+export async function loadTrustSignalTaxonomies() {
+  const taxonomies = [];
+  for (const file of TRUST_SIGNAL_FILES) {
+    const content = await readFile(join(ROOT, file), "utf8");
+    taxonomies.push(JSON.parse(content));
+  }
+  return taxonomies;
+}