feat: add Markdown compliance report format

src/cli/commands/scan.ts

@@ -7,6 +7,7 @@ import { reportJson } from '../../reporters/json.js';
 import { reportHtml } from '../../reporters/html.js';
 import { reportSarif } from '../../reporters/sarif.js';
 import { reportComplianceHtml, SUPPORTED_STANDARDS } from '../../reporters/compliance-html.js';
+import { reportComplianceMarkdown } from '../../reporters/compliance-markdown.js';
 import { loadConfig } from '../../config/loader.js';
 import { createSpinner } from '../ui.js';
 import { isRemoteUrl, parseTarget, cloneRepo } from '../../remote/clone.js';
@@ -30,6 +31,7 @@ export const scanCommand = new Command('scan')
   .option('--ai', 'Enable AI-powered analysis (requires ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_API_KEY)')
   .option('--model <model>', 'AI model to use (e.g., claude-sonnet-4-5-20250929, gpt-5-mini, gemini-2.5-flash)')
   .option('--report <standard>', `Generate compliance report (${SUPPORTED_STANDARDS.join('|')})`)
+  .option('--markdown [file]', 'Output compliance report as Markdown (use with --report)')
   .option('--upload', 'Upload results to Guard0 platform')
   .option('--include-tests', 'Include test files in agent graph (normally excluded)')
   .option('--show-all', 'Show all findings including suppressed utility-code ones')
@@ -58,6 +60,7 @@ export const scanCommand = new Command('scan')
     ai?: boolean;
     model?: string;
     report?: string;
+    markdown?: string | boolean;
     upload?: boolean;
     includeTests?: boolean;
     showAll?: boolean;
@@ -254,14 +257,28 @@ export const scanCommand = new Command('scan')
 
       // Generate compliance report
       if (options.report) {
-        const reportPath = path.join(resolvedPath, `g0-${options.report}-report.html`);
-        try {
-          reportComplianceHtml(result, options.report, reportPath);
-          if (!options.quiet) {
-            console.log(`\n  Compliance report (${options.report}) written to: ${reportPath}`);
+        if (options.markdown != null) {
+          const mdPath = typeof options.markdown === 'string'
+            ? options.markdown
+            : path.join(resolvedPath, `g0-${options.report}-report.md`);
+          try {
+            reportComplianceMarkdown(result, options.report, mdPath);
+            if (!options.quiet) {
+              console.log(`\n  Compliance report (${options.report}) written to: ${mdPath}`);
+            }
+          } catch (err) {
+            console.error(`  Report generation failed: ${err instanceof Error ? err.message : err}`);
+          }
+        } else {
+          const reportPath = path.join(resolvedPath, `g0-${options.report}-report.html`);
+          try {
+            reportComplianceHtml(result, options.report, reportPath);
+            if (!options.quiet) {
+              console.log(`\n  Compliance report (${options.report}) written to: ${reportPath}`);
+            }
+          } catch (err) {
+            console.error(`  Report generation failed: ${err instanceof Error ? err.message : err}`);
           }
-        } catch (err) {
-          console.error(`  Report generation failed: ${err instanceof Error ? err.message : err}`);
         }
       }
 

src/reporters/compliance-html.ts

@@ -156,7 +156,7 @@ function assessControl(
   };
 }
 
-function generateCompliance(standard: string, result: ScanResult): ComplianceResult {
+export function generateCompliance(standard: string, result: ScanResult): ComplianceResult {
   const controls = STANDARD_CONTROLS[standard];
   if (!controls) {
     throw new Error(`Unknown standard: ${standard}. Supported: ${Object.keys(STANDARD_CONTROLS).join(', ')}`);

src/reporters/compliance-markdown.ts

@@ -0,0 +1,59 @@
+import type { ScanResult } from '../types/score.js';
+import * as fs from 'node:fs';
+import { generateCompliance, SUPPORTED_STANDARDS } from './compliance-html.js';
+
+export { SUPPORTED_STANDARDS };
+
+function statusIcon(s: string): string {
+  return s === 'pass' ? '✅' : s === 'fail' ? '❌' : '⚠️';
+}
+
+export function reportComplianceMarkdown(
+  result: ScanResult,
+  standard: string,
+  outputPath: string,
+): void {
+  const compliance = generateCompliance(standard, result);
+  const date = new Date().toISOString().split('T')[0];
+
+  const lines: string[] = [];
+
+  lines.push(`# ${compliance.standardName} — Compliance Report`);
+  lines.push('');
+  lines.push(`**Score:** ${result.score.overall}/100 (${result.score.grade})  `);
+  lines.push(`**Findings:** ${result.findings.length}  `);
+  lines.push(`**Generated:** ${date} by Guard0`);
+  lines.push('');
+
+  // Summary
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(`| Metric | Value |`);
+  lines.push(`|--------|-------|`);
+  lines.push(`| Compliance Score | ${Math.round(compliance.overallScore)}% |`);
+  lines.push(`| Pass | ${compliance.passCount} |`);
+  lines.push(`| Partial | ${compliance.partialCount} |`);
+  lines.push(`| Fail | ${compliance.failCount} |`);
+  lines.push('');
+
+  // Controls table
+  lines.push('## Controls');
+  lines.push('');
+  lines.push('| Status | Control | Name | Findings | Notes |');
+  lines.push('|--------|---------|------|----------|-------|');
+
+  for (const c of compliance.controls) {
+    const icon = statusIcon(c.status);
+    const findings = c.findings.length > 0 ? c.findings.map((f) => `\`${f}\``).join(', ') : '—';
+    lines.push(`| ${icon} ${c.status.toUpperCase()} | \`${c.id}\` | ${c.name} | ${findings} | ${c.notes} |`);
+  }
+
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push(`*Guard0 AI Agent Security Scanner · guard0.ai*  `);
+  lines.push(`*Standard: ${compliance.standardName} · ${compliance.controls.length} controls assessed*`);
+  lines.push('');
+
+  fs.writeFileSync(outputPath, lines.join('\n'), 'utf-8');
+}

tests/unit/compliance-markdown.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { reportComplianceMarkdown } from '../../src/reporters/compliance-markdown.js';
+import type { ScanResult } from '../../src/types/score.js';
+import type { Finding } from '../../src/types/finding.js';
+
+function makeFinding(overrides: Partial<Finding> = {}): Finding {
+  return {
+    id: 'f-1',
+    ruleId: 'AA-GI-001',
+    title: 'Test finding',
+    description: 'A test finding',
+    severity: 'critical',
+    confidence: 'high',
+    domain: 'goal-integrity',
+    location: { file: 'agent.py', line: 42, column: 0 },
+    remediation: 'Fix it',
+    standards: {},
+    ...overrides,
+  };
+}
+
+function makeScanResult(findings: Finding[] = []): ScanResult {
+  return {
+    score: { overall: 65, grade: 'C', domains: [] },
+    findings,
+    graph: { agents: [], tools: [], edges: [], models: [] } as any,
+    duration: 100,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+describe('compliance-markdown reporter', () => {
+  const tmpFiles: string[] = [];
+
+  function tmpPath(): string {
+    const p = path.join(os.tmpdir(), `g0-test-${Date.now()}-${Math.random().toString(36).slice(2)}.md`);
+    tmpFiles.push(p);
+    return p;
+  }
+
+  afterEach(() => {
+    for (const f of tmpFiles) {
+      try { fs.unlinkSync(f); } catch {}
+    }
+    tmpFiles.length = 0;
+  });
+
+  it('generates a valid markdown file for iso42001', () => {
+    const out = tmpPath();
+    reportComplianceMarkdown(makeScanResult(), 'iso42001', out);
+    const md = fs.readFileSync(out, 'utf-8');
+
+    expect(md).toContain('# ISO 42001 AI Management System');
+    expect(md).toContain('## Summary');
+    expect(md).toContain('## Controls');
+    expect(md).toContain('| Status | Control | Name | Findings | Notes |');
+    expect(md).toContain('guard0.ai');
+  });
+
+  it('shows pass for controls with no findings', () => {
+    const out = tmpPath();
+    reportComplianceMarkdown(makeScanResult([]), 'iso42001', out);
+    const md = fs.readFileSync(out, 'utf-8');
+
+    expect(md).toContain('✅ PASS');
+    expect(md).not.toContain('❌ FAIL');
+  });
+
+  it('shows fail for controls with critical findings', () => {
+    const out = tmpPath();
+    const finding = makeFinding({ severity: 'critical', domain: 'goal-integrity' });
+    reportComplianceMarkdown(makeScanResult([finding]), 'iso42001', out);
+    const md = fs.readFileSync(out, 'utf-8');
+
+    expect(md).toContain('❌ FAIL');
+    expect(md).toContain('`AA-GI-001`');
+  });
+
+  it('shows partial for controls with medium findings', () => {
+    const out = tmpPath();
+    const finding = makeFinding({ severity: 'medium', domain: 'data-leakage' });
+    reportComplianceMarkdown(makeScanResult([finding]), 'iso42001', out);
+    const md = fs.readFileSync(out, 'utf-8');
+
+    expect(md).toContain('⚠️ PARTIAL');
+  });
+
+  it('throws for unknown standard', () => {
+    const out = tmpPath();
+    expect(() => reportComplianceMarkdown(makeScanResult(), 'unknown-standard', out)).toThrow('Unknown standard');
+  });
+
+  it('works with all supported standards', () => {
+    const standards = ['owasp-agentic', 'iso42001', 'nist-ai-rmf', 'soc2', 'eu-ai-act'];
+    for (const std of standards) {
+      const out = tmpPath();
+      reportComplianceMarkdown(makeScanResult(), std, out);
+      const md = fs.readFileSync(out, 'utf-8');
+      expect(md).toContain('## Controls');
+    }
+  });
+
+  it('includes score and grade', () => {
+    const out = tmpPath();
+    reportComplianceMarkdown(makeScanResult(), 'iso42001', out);
+    const md = fs.readFileSync(out, 'utf-8');
+
+    expect(md).toContain('65/100');
+    expect(md).toContain('(C)');
+  });
+});