agent-security-lens 0.1.0

package/server.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.professor2k8/agent-security-lens",
+  "title": "AgentSecurityLens",
+  "description": "Security intelligence MCP for agents to review MCPs, Skills and tools before installation.",
+  "status": "active",
+  "repository": {
+    "url": "https://github.com/professor2k8/agent-security-lens",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "agent-security-lens",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "ASL_API_URL",
+          "description": "AgentSecurityLens Cloud Intelligence API URL.",
+          "isRequired": false,
+          "default": "https://api.agentsecuritylens.com"
+        },
+        {
+          "name": "ASL_API_KEY",
+          "description": "Optional API key for Team, Pro or Enterprise use.",
+          "isRequired": false,
+          "isSecret": true
+        },
+        {
+          "name": "ASL_MODE",
+          "description": "Set to local for offline fallback mode.",
+          "isRequired": false,
+          "default": "online"
+        }
+      ]
+    }
+  ]
+}

package/src/assessment/assess.mjs

@@ -0,0 +1,108 @@
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { discoverFiles } from "../core/files.mjs";
+import { extractJsonObservations } from "../observations/json-observations.mjs";
+import { findingsFromObservations } from "../observations/observation-rules.mjs";
+import { loadProfiles, resolveProfileSelection } from "../profiles/load-profiles.mjs";
+import { loadRecommendationPacks } from "../recommendations/load-recommendations.mjs";
+import { applyRecommendations } from "../recommendations/match-recommendations.mjs";
+import { loadRulePacks } from "../rules/load-rules.mjs";
+import { matchRules } from "../rules/match-rules.mjs";
+import { applySupersedes } from "../rules/supersedes.mjs";
+import { deriveTrustSignals, summarizeTrustSignals } from "../trust/derive-trust-signals.mjs";
+import { loadTrustSignalTaxonomies } from "../trust/load-trust-signals.mjs";
+import { groupByRiskDomain } from "./risk-domains.mjs";
+import { summarize } from "./summarize.mjs";
+
+export async function assess({ targetPath, requestedProfile }) {
+  const startedAt = new Date().toISOString();
+  const root = resolve(targetPath);
+  const profiles = await loadProfiles();
+  const profileSelection = await resolveProfileSelection({ profiles, requestedProfile, root });
+  const matchedProfiles = profileSelection.profiles;
+  const rulePacks = await loadRulePacks(matchedProfiles);
+  const recommendationPacks = await loadRecommendationPacks();
+  const trustSignalTaxonomies = await loadTrustSignalTaxonomies();
+  const files = await discoverFiles(root);
+  const textFindings = await matchRules({ root, files, profiles: matchedProfiles, rulePacks });
+  const observations = await extractJsonObservations(files);
+  const observationFindings = findingsFromObservations({
+    observations,
+    profileIds: matchedProfiles.map((profile) => profile.id)
+  });
+  const findings = applyRecommendations(
+    applySupersedes([...observationFindings, ...textFindings]),
+    recommendationPacks
+  );
+  const trustSignals = deriveTrustSignals({ findings, taxonomies: trustSignalTaxonomies });
+  const summary = summarize(findings, matchedProfiles);
+  summary.trust_signal_summary = summarizeTrustSignals(trustSignals);
+  const riskDomains = groupByRiskDomain(findings);
+  const completedAt = new Date().toISOString();
+  const assessmentId = createHash("sha256")
+    .update([root, startedAt, completedAt, profileSelection.selected_profile].join("|"))
+    .digest("hex")
+    .slice(0, 16);
+
+  return {
+    schema_version: "0.1.0",
+    tool: {
+      name: "AgentSecurityLens",
+      version: "0.1.0-alpha.0"
+    },
+    assessment: {
+      id: assessmentId,
+      target_path: root,
+      target_url: pathToFileURL(root).href,
+      started_at: startedAt,
+      completed_at: completedAt
+    },
+    lineage: {
+      profile_selection: {
+        mode: profileSelection.mode,
+        requested_profile: profileSelection.requested_profile,
+        selected_profile: profileSelection.selected_profile,
+        detection_signals: profileSelection.detection_signals
+      },
+      algorithms: [
+        { id: "json-observation-extractor", version: "0.1.0" },
+        { id: "observation-to-finding-rules", version: "0.1.0" },
+        { id: "finding-supersedes", version: "0.1.0" },
+        { id: "recommendation-matcher", version: "0.1.0" },
+        { id: "trust-signal-deriver", version: "0.1.0" },
+        { id: summary.scoring_model, version: "0.1.0" }
+      ]
+    },
+    profiles: matchedProfiles.map((profile) => ({
+      id: profile.id,
+      version: profile.version,
+      status: profile.status,
+      confidence: profile.confidence,
+      coverage: profile.coverage,
+      known_limitations: profile.known_limitations
+    })),
+    rule_packs: rulePacks.map((pack) => ({
+      id: pack.id,
+      version: pack.version,
+      rule_count: pack.rules.length
+    })),
+    recommendation_packs: recommendationPacks.map((pack) => ({
+      id: pack.id,
+      version: pack.version,
+      status: pack.status,
+      recommendation_count: pack.recommendations.length
+    })),
+    trust_signal_taxonomies: trustSignalTaxonomies.map((taxonomy) => ({
+      id: taxonomy.id,
+      version: taxonomy.version,
+      status: taxonomy.status,
+      signal_count: taxonomy.signals.length
+    })),
+    trust_signals: trustSignals,
+    observations,
+    summary,
+    risk_domains: riskDomains,
+    findings
+  };
+}

package/src/assessment/discover-targets.mjs

@@ -0,0 +1,127 @@
+import { readdir } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+
+const IGNORED_DIRS = new Set([
+  ".git",
+  ".agentsecuritylens",
+  ".agentsecuritylens-test",
+  "node_modules",
+  "dist",
+  "build",
+  ".next",
+  ".cache",
+  "__pycache__"
+]);
+
+const MARKERS = [
+  { profile: "openclaw-like", file: "openclaw.json", reason: "OpenClaw config" },
+  { profile: "openclaw-like", file: ".openclaw/openclaw.json", reason: "OpenClaw local config" },
+  { profile: "openclaw-like", file: "SOUL.md", reason: "OpenClaw instruction file" },
+  { profile: "openclaw-like", file: "TOOLS.md", reason: "OpenClaw tool manifest" },
+  { profile: "openclaw-like", file: "workspace/skills", reason: "OpenClaw skills workspace" },
+  { profile: "hermes-like", file: ".hermes", reason: "Hermes config directory" },
+  { profile: "hermes-like", file: ".hermes/config.json", reason: "Hermes JSON config" },
+  { profile: "hermes-like", file: ".hermes/config.yaml", reason: "Hermes YAML config" },
+  { profile: "hermes-like", file: "optional-mcps", reason: "Hermes optional MCPs" },
+  { profile: "hermes-like", file: "optional-skills", reason: "Hermes optional skills" },
+  { profile: "hermes-like", file: "gateway", reason: "Hermes gateway" },
+  { profile: "hermes-like", file: "cron", reason: "Hermes scheduled runs" },
+  { profile: "skill-runtime", file: "SKILL.md", reason: "Agent skill definition" },
+  { profile: "mcp-server", file: "mcp.json", reason: "MCP manifest" }
+];
+
+async function listEntries(dir) {
+  try {
+    return await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+async function hasPath(root, path) {
+  const parts = path.split("/");
+  let entries = await listEntries(root);
+  for (let index = 0; index < parts.length; index += 1) {
+    const part = parts[index];
+    const entry = entries.find((item) => item.name.toLowerCase() === part.toLowerCase());
+    if (!entry) return false;
+    if (index === parts.length - 1) return true;
+    if (!entry.isDirectory()) return false;
+    entries = await listEntries(join(root, entry.name));
+  }
+  return false;
+}
+
+function parentTargetForMarker(dir, markerFile) {
+  if (markerFile === "SKILL.md") return dir;
+  return dir;
+}
+
+function confidenceFor(signals) {
+  if (signals.length >= 3) return 0.9;
+  if (signals.length === 2) return 0.78;
+  return 0.62;
+}
+
+function labelFor(path, workspaceRoot) {
+  const rel = relative(workspaceRoot, path).replaceAll("\\", "/");
+  return rel || ".";
+}
+
+export async function discoverTargets({ workspacePath, maxDepth = 4 }) {
+  const workspaceRoot = resolve(workspacePath);
+  const candidates = new Map();
+
+  async function inspectDir(dir, depth) {
+    const matched = [];
+    for (const marker of MARKERS) {
+      if (await hasPath(dir, marker.file)) {
+        matched.push(marker);
+      }
+    }
+
+    if (matched.length) {
+      const targetPath = parentTargetForMarker(dir, matched[0].file);
+      const existing = candidates.get(targetPath) || {
+        path: targetPath,
+        label: labelFor(targetPath, workspaceRoot),
+        profile: matched[0].profile,
+        signals: []
+      };
+      for (const marker of matched) {
+        existing.signals.push({
+          profile: marker.profile,
+          marker: marker.file,
+          reason: marker.reason
+        });
+      }
+      const byProfile = new Map();
+      for (const signal of existing.signals) {
+        byProfile.set(signal.profile, (byProfile.get(signal.profile) || 0) + 1);
+      }
+      existing.profile = [...byProfile.entries()].sort((a, b) => b[1] - a[1])[0][0];
+      existing.confidence = confidenceFor(existing.signals);
+      candidates.set(targetPath, existing);
+    }
+
+    if (depth >= maxDepth) return;
+    for (const entry of await listEntries(dir)) {
+      if (!entry.isDirectory() || IGNORED_DIRS.has(entry.name)) continue;
+      await inspectDir(join(dir, entry.name), depth + 1);
+    }
+  }
+
+  await inspectDir(workspaceRoot, 0);
+  const targets = [...candidates.values()].sort((a, b) => a.label.localeCompare(b.label));
+  const deduped = targets.filter((target) => {
+    return !targets.some((other) => {
+      if (other === target || other.profile !== target.profile) return false;
+      const rel = relative(other.path, target.path);
+      return rel && !rel.startsWith("..") && rel !== "." && !rel.includes(":");
+    });
+  });
+  return {
+    workspace_path: workspaceRoot,
+    targets: deduped
+  };
+}

package/src/assessment/risk-domains.mjs

@@ -0,0 +1,83 @@
+const DOMAIN_DEFINITIONS = [
+  {
+    id: "mcp",
+    title: "MCP",
+    match: (finding) => finding.permissions.includes("mcp-tool-access") || finding.rule_id.includes("mcp")
+  },
+  {
+    id: "skills",
+    title: "Skills",
+    match: (finding) => finding.permissions.includes("skill-installation") || finding.rule_id.includes("skill")
+  },
+  {
+    id: "remote-triggers",
+    title: "Remote Triggers",
+    match: (finding) => finding.permissions.includes("remote-trigger")
+  },
+  {
+    id: "scheduler",
+    title: "Scheduler",
+    match: (finding) => finding.permissions.includes("scheduled-execution")
+  },
+  {
+    id: "credentials",
+    title: "Credentials",
+    match: (finding) => finding.permissions.includes("credential-access") || finding.permissions.includes("env-read")
+  },
+  {
+    id: "execution",
+    title: "Execution",
+    match: (finding) => finding.category === "execution-risk"
+  },
+  {
+    id: "supply-chain",
+    title: "Supply Chain",
+    match: (finding) => finding.category === "supply-chain-risk"
+  }
+];
+
+const severityRank = {
+  critical: 5,
+  high: 4,
+  medium: 3,
+  low: 2,
+  info: 1
+};
+
+function highestSeverity(findings) {
+  return findings.reduce((highest, finding) => {
+    if (!highest) return finding.severity;
+    return severityRank[finding.severity] > severityRank[highest] ? finding.severity : highest;
+  }, null);
+}
+
+export function groupByRiskDomain(findings) {
+  const domains = [];
+  const assigned = new Set();
+
+  for (const definition of DOMAIN_DEFINITIONS) {
+    const domainFindings = findings.filter((finding) => definition.match(finding));
+    if (!domainFindings.length) continue;
+    for (const finding of domainFindings) assigned.add(finding.id);
+    domains.push({
+      id: definition.id,
+      title: definition.title,
+      count: domainFindings.length,
+      highest_severity: highestSeverity(domainFindings),
+      findings: domainFindings.map((finding) => finding.id)
+    });
+  }
+
+  const otherFindings = findings.filter((finding) => !assigned.has(finding.id));
+  if (otherFindings.length) {
+    domains.push({
+      id: "other",
+      title: "Other",
+      count: otherFindings.length,
+      highest_severity: highestSeverity(otherFindings),
+      findings: otherFindings.map((finding) => finding.id)
+    });
+  }
+
+  return domains;
+}

package/src/assessment/summarize.mjs

@@ -0,0 +1,57 @@
+const severityWeights = {
+  critical: 22,
+  high: 12,
+  medium: 5,
+  low: 1,
+  info: 0
+};
+
+function categoryMultiplier(category) {
+  if (category === "execution-risk") return 1.15;
+  if (category === "data-exposure-risk") return 1.1;
+  if (category === "supply-chain-risk") return 1.05;
+  return 1;
+}
+
+export function summarize(findings, profiles = []) {
+  const bySeverity = {};
+  const byCategory = {};
+
+  for (const finding of findings) {
+    bySeverity[finding.severity] = (bySeverity[finding.severity] || 0) + 1;
+    byCategory[finding.category] = (byCategory[finding.category] || 0) + 1;
+  }
+
+  const rawPenalty = findings.reduce((total, finding) => {
+    const base = severityWeights[finding.severity] || 0;
+    const confidence = typeof finding.confidence === "number" ? finding.confidence : 0.7;
+    return total + base * confidence * categoryMultiplier(finding.category);
+  }, 0);
+
+  const profileCoverageAverage = profiles.length
+    ? profiles.reduce((total, profile) => total + (profile.coverage || 0), 0) / profiles.length
+    : 0.5;
+  const lowCoveragePenalty = profileCoverageAverage < 0.5 ? 6 : 0;
+  const penalty = Math.round(rawPenalty + lowCoveragePenalty);
+
+  const topFindings = findings
+    .slice()
+    .sort((a, b) => (severityWeights[b.severity] || 0) - (severityWeights[a.severity] || 0))
+    .slice(0, 5)
+    .map((finding) => ({
+      title: finding.title,
+      severity: finding.severity,
+      category: finding.category,
+      evidence: finding.evidence
+    }));
+
+  return {
+    total_findings: findings.length,
+    by_severity: bySeverity,
+    by_category: byCategory,
+    trust_score: Math.max(0, 100 - penalty),
+    scoring_model: "simple-penalty@0.1.0",
+    profile_coverage_average: Number(profileCoverageAverage.toFixed(2)),
+    top_findings: topFindings
+  };
+}

package/src/core/files.mjs

@@ -0,0 +1,74 @@
+import { readdir, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+
+const DEFAULT_IGNORES = new Set([
+  ".git",
+  "node_modules",
+  "dist",
+  "build",
+  ".next",
+  ".cache",
+  "__pycache__"
+]);
+
+const MAX_FILE_SIZE_BYTES = 512 * 1024;
+const SUPPORTED_EXTENSIONS = new Set([
+  "",
+  ".md",
+  ".txt",
+  ".json",
+  ".jsonc",
+  ".yaml",
+  ".yml",
+  ".toml",
+  ".js",
+  ".mjs",
+  ".cjs",
+  ".ts",
+  ".tsx",
+  ".py",
+  ".sh",
+  ".bash",
+  ".zsh",
+  ".ps1",
+  ".env",
+  ".example"
+]);
+
+function extnameLoose(path) {
+  const name = path.toLowerCase();
+  if (name.endsWith(".env") || name.includes(".env.")) return ".env";
+  const index = name.lastIndexOf(".");
+  return index === -1 ? "" : name.slice(index);
+}
+
+export async function discoverFiles(root) {
+  const files = [];
+
+  async function walk(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (DEFAULT_IGNORES.has(entry.name)) continue;
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+
+      const info = await stat(fullPath);
+      if (info.size > MAX_FILE_SIZE_BYTES) continue;
+      const ext = extnameLoose(fullPath);
+      if (!SUPPORTED_EXTENSIONS.has(ext)) continue;
+
+      files.push({
+        path: fullPath,
+        relative_path: relative(root, fullPath).replaceAll("\\", "/"),
+        size: info.size
+      });
+    }
+  }
+
+  await walk(root);
+  return files;
+}