agentsafe 0.1.0

package/src/rules/scan.ts

@@ -0,0 +1,544 @@
+import { lstat, readdir, readFile } from "node:fs/promises";
+import { resolve, join, relative, sep } from "node:path";
+import { parse } from "yaml";
+
+import type { Finding, ScanReport } from "./types.js";
+
+const ROOT_RULE_FILES = ["AGENTS.md", "CLAUDE.md", "GEMINI.md", ".cursorrules"];
+const MAX_ALWAYS_APPLY_LINES = 500;
+const MAX_ALWAYS_APPLY_RULES = 5;
+
+interface ParsedRule {
+  path: string;
+  content: string;
+  body: string;
+  bodyStartLine: number;
+  globs: string[];
+  alwaysApply: boolean;
+}
+
+interface PatternDefinition {
+  code: string;
+  message: string;
+  pattern: RegExp;
+}
+
+const suspiciousPatterns: PatternDefinition[] = [
+  {
+    code: "ignore-previous-instructions",
+    message: "Instruction asks to ignore previous instructions.",
+    pattern: /\bignore\s+(?:all\s+)?previous\s+instructions\b/i,
+  },
+  {
+    code: "reveal-secrets",
+    message: "Instruction asks to reveal secrets.",
+    pattern: /\breveal\s+(?:the\s+)?secrets?\b/i,
+  },
+  {
+    code: "read-dot-env",
+    message: "Instruction asks to read a .env file.",
+    pattern: /\bread\s+(?:the\s+)?(?:file\s+)?\.env\b/i,
+  },
+  {
+    code: "print-environment-variables",
+    message: "Instruction asks to print environment variables.",
+    pattern: /\bprint\s+(?:all\s+)?environment\s+variables\b/i,
+  },
+  {
+    code: "send-tokens",
+    message: "Instruction asks to send tokens.",
+    pattern: /\bsend\s+(?:the\s+)?tokens?\b/i,
+  },
+  {
+    code: "exfiltrate",
+    message: "Instruction contains an exfiltration request.",
+    pattern: /\bexfiltrat(?:e|es|ed|ing|ion)\b/i,
+  },
+  {
+    code: "disable-safety",
+    message: "Instruction asks to disable safety controls.",
+    pattern: /\bdisable\s+(?:all\s+)?safety\b/i,
+  },
+];
+
+const secretPatterns: PatternDefinition[] = [
+  {
+    code: "anthropic-key",
+    message: "Possible Anthropic API key detected; value omitted.",
+    pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g,
+  },
+  {
+    code: "openai-key",
+    message: "Possible OpenAI API key detected; value omitted.",
+    pattern: /\bsk-(?!ant-)(?:proj-)?[A-Za-z0-9_-]{20,}\b/g,
+  },
+  {
+    code: "github-token",
+    message: "Possible GitHub token detected; value omitted.",
+    pattern: /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})\b/g,
+  },
+  {
+    code: "aws-access-key",
+    message: "Possible AWS access key ID detected; value omitted.",
+    pattern: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g,
+  },
+  {
+    code: "generic-api-key",
+    message: "Possible API key or token assignment detected; value omitted.",
+    pattern:
+      /\b(?:api[\s_-]?key|access[\s_-]?token|auth[\s_-]?token|token|secret)\b\s*[:=]\s*["']?[A-Za-z0-9][A-Za-z0-9._/-]{15,}/gi,
+  },
+];
+
+const vagueInstructionPattern =
+  /\b(?:write clean code|follow best practices|use meaningful (?:variable )?names|make (?:the )?code readable|write maintainable code|keep (?:the )?code simple)\b/i;
+const concreteExamplePattern =
+  /(?:^|\n)\s*#{1,6}\s+examples?\b|\b(?:for example|e\.g\.)\b|```[\s\S]*?```/i;
+
+export async function scanRules(rootInput: string): Promise<ScanReport> {
+  const root = resolve(rootInput);
+  await assertDirectory(root, rootInput);
+
+  const absoluteFiles = await discoverRuleFiles(root);
+  const findings: Finding[] = [];
+  const rules: ParsedRule[] = [];
+
+  for (const absolutePath of absoluteFiles) {
+    const relativePath = toReportPath(relative(root, absolutePath));
+    let content: string;
+
+    try {
+      content = stripBom(await readFile(absolutePath, "utf8"));
+    } catch {
+      throw new Error(`Unable to read rule file: ${relativePath}`);
+    }
+
+    const parsed = absolutePath.toLowerCase().endsWith(".mdc")
+      ? parseMdc(relativePath, content, findings)
+      : {
+          path: relativePath,
+          content,
+          body: content,
+          bodyStartLine: 1,
+          globs: [],
+          alwaysApply: false,
+        };
+
+    rules.push(parsed);
+    inspectBody(parsed, findings);
+    inspectSuspiciousInstructions(parsed, findings);
+    inspectSecrets(parsed, findings);
+  }
+
+  inspectRuleSet(rules, findings);
+  findings.sort(compareFindings);
+
+  const high = findings.filter((finding) => finding.severity === "high").length;
+  const warnings = findings.length - high;
+
+  return {
+    schemaVersion: 1,
+    tool: { name: "AgentSafe", version: "0.1.0" },
+    target: ".",
+    files: rules.map((rule) => rule.path),
+    findings,
+    summary: {
+      files: rules.length,
+      high,
+      warnings,
+      total: findings.length,
+    },
+  };
+}
+
+async function assertDirectory(root: string, input: string): Promise<void> {
+  try {
+    const stats = await lstat(root);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+      throw new Error();
+    }
+  } catch {
+    throw new Error(`Scan target is not a directory: ${input}`);
+  }
+}
+
+async function discoverRuleFiles(root: string): Promise<string[]> {
+  const files: string[] = [];
+
+  for (const fileName of ROOT_RULE_FILES) {
+    const candidate = join(root, fileName);
+    if (await isRegularFile(candidate)) {
+      files.push(candidate);
+    }
+  }
+
+  const cursorRulesDirectory = join(root, ".cursor", "rules");
+  try {
+    const entries = await readdir(cursorRulesDirectory, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && !entry.isSymbolicLink() && entry.name.toLowerCase().endsWith(".mdc")) {
+        files.push(join(cursorRulesDirectory, entry.name));
+      }
+    }
+  } catch (error) {
+    if (!isMissingPathError(error)) {
+      throw new Error("Unable to read .cursor/rules directory.");
+    }
+  }
+
+  return files.sort((left, right) => compareText(toReportPath(left), toReportPath(right)));
+}
+
+async function isRegularFile(path: string): Promise<boolean> {
+  try {
+    const stats = await lstat(path);
+    return stats.isFile() && !stats.isSymbolicLink();
+  } catch (error) {
+    if (isMissingPathError(error)) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function isMissingPathError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: unknown }).code === "ENOENT"
+  );
+}
+
+function parseMdc(path: string, content: string, findings: Finding[]): ParsedRule {
+  const lines = content.split(/\r?\n/);
+  const emptyResult = {
+    path,
+    content,
+    body: content,
+    bodyStartLine: 1,
+    globs: [],
+    alwaysApply: false,
+  };
+
+  if (lines[0]?.trim() !== "---") {
+    findings.push({
+      code: "missing-frontmatter",
+      category: "frontmatter",
+      severity: "warning",
+      message: "Cursor rule has no YAML frontmatter.",
+      path,
+      line: 1,
+    });
+    return emptyResult;
+  }
+
+  const closingIndex = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+  if (closingIndex === -1) {
+    findings.push({
+      code: "invalid-frontmatter",
+      category: "frontmatter",
+      severity: "warning",
+      message: "YAML frontmatter has no closing delimiter.",
+      path,
+      line: 1,
+    });
+    return { ...emptyResult, body: "" };
+  }
+
+  const frontmatterSource = lines.slice(1, closingIndex).join("\n");
+  const body = lines.slice(closingIndex + 1).join("\n");
+  let frontmatter: unknown;
+
+  try {
+    frontmatter = parse(frontmatterSource, { schema: "core" });
+  } catch {
+    findings.push({
+      code: "invalid-frontmatter",
+      category: "frontmatter",
+      severity: "warning",
+      message: "YAML frontmatter could not be parsed.",
+      path,
+      line: 1,
+    });
+    return { ...emptyResult, body };
+  }
+
+  if (!isRecord(frontmatter)) {
+    findings.push({
+      code: "invalid-frontmatter",
+      category: "frontmatter",
+      severity: "warning",
+      message: "YAML frontmatter must be a mapping.",
+      path,
+      line: 1,
+    });
+    return { ...emptyResult, body };
+  }
+
+  validateOptionalStringField(frontmatter, "description", path, lines, closingIndex, findings);
+
+  let globs: string[] = [];
+  if (!("globs" in frontmatter)) {
+    addMissingFieldFinding("globs", path, findings);
+  } else if (frontmatter.globs === null || frontmatter.globs === "") {
+    globs = [];
+  } else if (typeof frontmatter.globs === "string") {
+    globs = splitGlobList(frontmatter.globs);
+  } else if (
+    Array.isArray(frontmatter.globs) &&
+    frontmatter.globs.every((glob): glob is string => typeof glob === "string")
+  ) {
+    globs = frontmatter.globs.flatMap(splitGlobList);
+  } else {
+    addInvalidFieldFinding("globs", "a string, string array, or empty value", path, lines, closingIndex, findings);
+  }
+
+  let alwaysApply = false;
+  if (!("alwaysApply" in frontmatter)) {
+    addMissingFieldFinding("alwaysApply", path, findings);
+  } else if (typeof frontmatter.alwaysApply === "boolean") {
+    alwaysApply = frontmatter.alwaysApply;
+  } else {
+    addInvalidFieldFinding("alwaysApply", "a boolean", path, lines, closingIndex, findings);
+  }
+
+  return { path, content, body, bodyStartLine: closingIndex + 2, globs, alwaysApply };
+}
+
+function validateOptionalStringField(
+  frontmatter: Record<string, unknown>,
+  field: string,
+  path: string,
+  lines: string[],
+  closingIndex: number,
+  findings: Finding[],
+): void {
+  if (!(field in frontmatter)) {
+    addMissingFieldFinding(field, path, findings);
+  } else if (frontmatter[field] !== null && typeof frontmatter[field] !== "string") {
+    addInvalidFieldFinding(field, "a string or empty value", path, lines, closingIndex, findings);
+  }
+}
+
+function addMissingFieldFinding(field: string, path: string, findings: Finding[]): void {
+  findings.push({
+    code: `missing-${toKebabCase(field)}`,
+    category: "validation",
+    severity: "warning",
+    message: `Cursor frontmatter is missing the ${field} field.`,
+    path,
+    line: 1,
+  });
+}
+
+function addInvalidFieldFinding(
+  field: string,
+  expected: string,
+  path: string,
+  lines: string[],
+  closingIndex: number,
+  findings: Finding[],
+): void {
+  findings.push({
+    code: `invalid-${toKebabCase(field)}`,
+    category: "validation",
+    severity: "warning",
+    message: `Cursor frontmatter field ${field} must be ${expected}.`,
+    path,
+    line: findFieldLine(lines, closingIndex, field),
+  });
+}
+
+function findFieldLine(lines: string[], closingIndex: number, field: string): number {
+  const fieldPattern = new RegExp(`^\\s*${escapeRegExp(field)}\\s*:`);
+  const index = lines.slice(1, closingIndex).findIndex((line) => fieldPattern.test(line));
+  return index === -1 ? 1 : index + 2;
+}
+
+function splitGlobList(value: string): string[] {
+  const globs: string[] = [];
+  let current = "";
+  let depth = 0;
+
+  for (let index = 0; index < value.length; index += 1) {
+    const character = value[index];
+    if (character === undefined) {
+      continue;
+    }
+
+    if ("{[(".includes(character)) {
+      depth += 1;
+    } else if ("}])".includes(character) && depth > 0) {
+      depth -= 1;
+    }
+
+    if (character === "," && depth === 0 && value[index - 1] !== "\\") {
+      if (current.trim()) {
+        globs.push(current.trim());
+      }
+      current = "";
+    } else {
+      current += character;
+    }
+  }
+
+  if (current.trim()) {
+    globs.push(current.trim());
+  }
+
+  return globs;
+}
+
+function inspectBody(rule: ParsedRule, findings: Finding[]): void {
+  if (!rule.body.trim()) {
+    findings.push({
+      code: "empty-rule-body",
+      category: "quality",
+      severity: "warning",
+      message: "Rule body is empty.",
+      path: rule.path,
+      line: rule.bodyStartLine,
+    });
+  }
+
+  if (
+    vagueInstructionPattern.test(rule.body) &&
+    !concreteExamplePattern.test(rule.body)
+  ) {
+    const match = vagueInstructionPattern.exec(rule.body);
+    findings.push({
+      code: "vague-instruction",
+      category: "quality",
+      severity: "warning",
+      message: "Rule contains a vague instruction without a concrete example.",
+      path: rule.path,
+      line: match ? rule.bodyStartLine + lineNumberAt(rule.body, match.index) - 1 : rule.bodyStartLine,
+    });
+  }
+
+  if (rule.alwaysApply && countLines(rule.content) > MAX_ALWAYS_APPLY_LINES) {
+    findings.push({
+      code: "long-always-apply-rule",
+      category: "quality",
+      severity: "warning",
+      message: `Always-applied rule exceeds ${MAX_ALWAYS_APPLY_LINES} lines.`,
+      path: rule.path,
+      line: 1,
+    });
+  }
+}
+
+function inspectSuspiciousInstructions(rule: ParsedRule, findings: Finding[]): void {
+  for (const definition of suspiciousPatterns) {
+    const match = definition.pattern.exec(rule.content);
+    if (match) {
+      findings.push({
+        code: definition.code,
+        category: "suspicious-instruction",
+        severity: "high",
+        message: definition.message,
+        path: rule.path,
+        line: lineNumberAt(rule.content, match.index),
+      });
+    }
+  }
+}
+
+function inspectSecrets(rule: ParsedRule, findings: Finding[]): void {
+  for (const definition of secretPatterns) {
+    definition.pattern.lastIndex = 0;
+    const seenLines = new Set<number>();
+
+    for (const match of rule.content.matchAll(definition.pattern)) {
+      const line = lineNumberAt(rule.content, match.index ?? 0);
+      if (seenLines.has(line)) {
+        continue;
+      }
+      seenLines.add(line);
+      findings.push({
+        code: definition.code,
+        category: "secret",
+        severity: "high",
+        message: definition.message,
+        path: rule.path,
+        line,
+      });
+    }
+  }
+}
+
+function inspectRuleSet(rules: ParsedRule[], findings: Finding[]): void {
+  const alwaysApplyRules = rules.filter((rule) => rule.alwaysApply);
+  if (alwaysApplyRules.length > MAX_ALWAYS_APPLY_RULES) {
+    findings.push({
+      code: "too-many-always-apply-rules",
+      category: "quality",
+      severity: "warning",
+      message: `${alwaysApplyRules.length} rules use alwaysApply; recommended maximum is ${MAX_ALWAYS_APPLY_RULES}.`,
+    });
+  }
+
+  const globOwners = new Map<string, Set<string>>();
+  for (const rule of rules) {
+    for (const glob of rule.globs) {
+      const owners = globOwners.get(glob) ?? new Set<string>();
+      owners.add(rule.path);
+      globOwners.set(glob, owners);
+    }
+  }
+
+  for (const owners of globOwners.values()) {
+    if (owners.size > 1) {
+      const paths = [...owners].sort(compareText);
+      findings.push({
+        code: "duplicate-glob",
+        category: "quality",
+        severity: "warning",
+        message: `The same glob is used by multiple rules: ${paths.join(", ")}.`,
+      });
+    }
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stripBom(value: string): string {
+  return value.charCodeAt(0) === 0xfeff ? value.slice(1) : value;
+}
+
+function countLines(value: string): number {
+  return value ? value.split(/\r?\n/).length : 0;
+}
+
+function lineNumberAt(value: string, index: number): number {
+  return value.slice(0, index).split(/\r?\n/).length;
+}
+
+function toReportPath(value: string): string {
+  return sep === "/" ? value : value.split(sep).join("/");
+}
+
+function toKebabCase(value: string): string {
+  return value.replace(/[A-Z]/g, (character) => `-${character.toLowerCase()}`);
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function compareFindings(left: Finding, right: Finding): number {
+  const severityOrder = { high: 0, warning: 1 };
+  return (
+    severityOrder[left.severity] - severityOrder[right.severity] ||
+    compareText(left.path ?? "", right.path ?? "") ||
+    (left.line ?? 0) - (right.line ?? 0) ||
+    compareText(left.code, right.code)
+  );
+}
+
+function compareText(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}

package/src/rules/types.ts

@@ -0,0 +1,36 @@
+export type Severity = "high" | "warning";
+
+export type FindingCategory =
+  | "frontmatter"
+  | "validation"
+  | "quality"
+  | "suspicious-instruction"
+  | "secret";
+
+export interface Finding {
+  code: string;
+  category: FindingCategory;
+  severity: Severity;
+  message: string;
+  path?: string;
+  line?: number;
+}
+
+export interface ScanSummary {
+  files: number;
+  high: number;
+  warnings: number;
+  total: number;
+}
+
+export interface ScanReport {
+  schemaVersion: 1;
+  tool: {
+    name: "AgentSafe";
+    version: "0.1.0";
+  };
+  target: ".";
+  files: string[];
+  findings: Finding[];
+  summary: ScanSummary;
+}

package/test/scanner.test.mjs

@@ -0,0 +1,136 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test from "node:test";
+
+import { runCli } from "../dist/cli.js";
+import { formatJsonReport, formatMarkdownReport } from "../dist/rules/report.js";
+import { scanRules } from "../dist/rules/scan.js";
+
+const projectRoot = process.cwd();
+const safeFixture = join(projectRoot, "examples", "safe-rules");
+const unsafeFixture = join(projectRoot, "examples", "unsafe-rules");
+
+test("safe fixture has no findings", async () => {
+  const report = await scanRules(safeFixture);
+
+  assert.equal(report.summary.files, 5);
+  assert.equal(report.summary.total, 0);
+  assert.deepEqual(report.findings, []);
+  assert.ok(report.files.every((file) => !file.includes("\\")));
+});
+
+test("unsafe fixture covers rule hygiene, suspicious instructions, and secrets", async () => {
+  const report = await scanRules(unsafeFixture);
+  const codes = new Set(report.findings.map((finding) => finding.code));
+  const expectedCodes = [
+    "missing-frontmatter",
+    "empty-rule-body",
+    "duplicate-glob",
+    "too-many-always-apply-rules",
+    "vague-instruction",
+    "invalid-description",
+    "invalid-globs",
+    "invalid-always-apply",
+    "invalid-frontmatter",
+    "ignore-previous-instructions",
+    "reveal-secrets",
+    "read-dot-env",
+    "print-environment-variables",
+    "send-tokens",
+    "exfiltrate",
+    "disable-safety",
+    "openai-key",
+    "anthropic-key",
+    "github-token",
+    "aws-access-key",
+    "generic-api-key",
+  ];
+
+  for (const code of expectedCodes) {
+    assert.ok(codes.has(code), `expected finding ${code}`);
+  }
+  assert.ok(report.summary.high > 0);
+  assert.ok(report.summary.warnings > 0);
+});
+
+test("alwaysApply rules over 500 lines are reported", async () => {
+  const root = await mkdtemp(join(tmpdir(), "agentsafe-"));
+  const rulePath = join(root, ".cursor", "rules", "long.mdc");
+
+  try {
+    await mkdir(dirname(rulePath), { recursive: true });
+    const body = Array.from({ length: 501 }, (_, index) => `Specific instruction ${index + 1}.`).join("\n");
+    await writeFile(
+      rulePath,
+      `---\ndescription:\nglobs:\nalwaysApply: true\n---\n${body}\n`,
+      "utf8",
+    );
+
+    const report = await scanRules(root);
+    assert.ok(report.findings.some((finding) => finding.code === "long-always-apply-rule"));
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("JSON and Markdown reports never expose detected values", async () => {
+  const report = await scanRules(unsafeFixture);
+  const outputs = [formatJsonReport(report), formatMarkdownReport(report)];
+  const secretValues = [
+    "sk-test-AGENTSAFE000000000000000000",
+    "sk-ant-test-AGENTSAFE00000000000000",
+    "ghp_AGENTSAFETESTTOKEN0000000000000000",
+    "AKIAIOSFODNN7EXAMPLE",
+    "agentsafe_test_api_key_1234567890",
+  ];
+
+  for (const output of outputs) {
+    for (const secret of secretValues) {
+      assert.ok(!output.includes(secret));
+    }
+  }
+
+  const parsed = JSON.parse(outputs[0]);
+  assert.equal(parsed.schemaVersion, 1);
+  assert.equal(parsed.target, ".");
+});
+
+test("CLI returns zero for findings and emits pure JSON", async () => {
+  let stdout = "";
+  let stderr = "";
+  const exitCode = await runCli(
+    ["rules", "scan", unsafeFixture, "--json"],
+    projectRoot,
+    {
+      stdout: (value) => {
+        stdout += value;
+      },
+      stderr: (value) => {
+        stderr += value;
+      },
+    },
+  );
+
+  assert.equal(exitCode, 0);
+  assert.equal(stderr, "");
+  assert.ok(JSON.parse(stdout).summary.total > 0);
+});
+
+test("CLI rejects conflicting report flags", async () => {
+  let stderr = "";
+  const exitCode = await runCli(
+    ["rules", "scan", "--json", "--markdown"],
+    projectRoot,
+    {
+      stdout: () => {},
+      stderr: (value) => {
+        stderr += value;
+      },
+    },
+  );
+
+  assert.equal(exitCode, 1);
+  assert.match(stderr, /only one report format/i);
+});