tractatus/docs/DOCUMENT_SECURITY_GOVERNANCE.md

Document Security Governance Controls

Date: 2025-10-08 Created in response to: Accidental public deployment of sensitive documentation Status: IMPLEMENTED

---

Incident Summary

What happened:

• Security Audit Report, Koha Stripe Setup Guide, and Koha Production Deployment Guide were imported and deployed to production
• These documents contained sensitive information (credentials, vulnerabilities, payment setup, infrastructure details)
• Documents were marked public: true and audience: 'technical'
• No security validation occurred before deployment

Root cause:

• No distinction between audience (who it's FOR) and visibility (who can ACCESS it)
• Framework components (BoundaryEnforcer, MetacognitiveVerifier) didn't have rules for document security
• Import script lacked security classification logic

---

Solution Architecture

1. Document Visibility Model

NEW: Three-tier visibility system

visibility: 'public'        // Accessible via public API
visibility: 'internal'      // Only accessible to authenticated users
visibility: 'confidential'  // Restricted access, high sensitivity

Separate from audience:

audience: 'technical'  // WHO it's written for
visibility: 'internal' // WHO can access it

Example:

• API documentation: audience: 'technical', visibility: 'public' ✅
• Security audit: audience: 'technical', visibility: 'confidential' ✅
• Deployment guide: audience: 'technical', visibility: 'internal' ✅

2. Security Classification Metadata

NEW: Automatic content analysis

security_classification: {
  contains_credentials: boolean,
  contains_financial_info: boolean,
  contains_vulnerability_info: boolean,
  contains_infrastructure_details: boolean,
  requires_authentication: boolean
}

Automated keyword detection:

• Credentials: password, api_key, secret, token, mongodb_uri, stripe_secret
• Financial: stripe, payment, pricing, revenue, cost, billing
• Vulnerabilities: security audit, vulnerability, exploit, cve-
• Infrastructure: deployment, server, ssh, production environment, database credentials

3. Pre-Import Security Validation

NEW: validate-document-security.js

Blocks import if:

• Document contains credentials AND visibility is 'public' → ❌ BLOCKED
• Document contains vulnerabilities AND visibility is 'public' → ❌ BLOCKED

Warns if:

• Document contains financial info AND visibility is 'public' → ⚠️ WARNING
• Document contains infrastructure details AND visibility is 'public' → ⚠️ WARNING

Example output:

$ node scripts/validate-document-security.js "Security Audit Report" docs/SECURITY_AUDIT_REPORT.md

🔒 Security Validation: Security Audit Report
────────────────────────────────────────────────────────────

ISSUES:
  ❌ BLOCKED: Document contains credentials but is marked public
  ❌ BLOCKED: Document contains vulnerability information but is marked public

WARNINGS:
  ⚠️  WARNING: Document contains infrastructure details but is marked public
  ⚠️  RECOMMEND: Change visibility from 'public' to 'confidential'

CLASSIFICATION:
  Credentials: true
  Financial Info: false
  Vulnerabilities: true
  Infrastructure: true
  Recommended: confidential

────────────────────────────────────────────────────────────
❌ VALIDATION FAILED

4. Updated Import Script

NEW: Automatic security checks in import-technical-docs.js

// Security validation before import
const securityCheck = validateDocumentSecurity(docConfig, content_markdown);

if (!securityCheck.valid) {
  console.log(`  ❌ SECURITY VALIDATION FAILED`);
  errors++;
  continue; // Block import
}

// Store classification with document
const document = await Document.create({
  title: docConfig.title,
  visibility: docConfig.visibility || 'public',
  security_classification: securityCheck.classification,
  // ...
});

Documents now require explicit visibility:

{
  file: 'docs/claude-code-framework-enforcement.md',
  visibility: 'public', // ✅ EXPLICIT
  // ...
}

Sensitive docs removed from import list:

// REMOVED: Security Audit, Koha Stripe Setup, Koha Deployment
// These documents contain sensitive information and should NOT be public

5. API Filter Updates

NEW: documents.controller.js filters by visibility

// Build filter - only show public documents (not internal/confidential)
const filter = {
  $or: [
    { visibility: 'public' },
    { public: true, visibility: { $exists: false } } // Legacy support
  ]
};

Public API endpoints:

• /api/documents → Only returns visibility: 'public' documents
• /api/documents?audience=technical → Only returns visibility: 'public' AND audience: 'technical'

Internal documents: Require authentication (future implementation)

6. Framework Instruction

NEW: inst_012 - Document Security Requirement

Classification:

• Quadrant: SYSTEM
• Persistence: HIGH
• Temporal Scope: PERMANENT
• Verification: MANDATORY

Text:

"NEVER deploy documents marked 'internal' or 'confidential' to public production without explicit human approval. Documents containing credentials, security vulnerabilities, financial information, or infrastructure details MUST NOT be publicly accessible."

Enforcement: CrossReferenceValidator should check this before any document deployment

7. Pre-Action Check

NEW: Action type document-deployment

node scripts/pre-action-check.js document-deployment "Import technical docs to production"

Requirements:

• BoundaryEnforcer must have been used (security decision)
• CrossReferenceValidator must have checked instructions (inst_012)

---

Usage Guidelines

For Developers: Importing Documents

1. Classify document visibility:

{
  file: 'docs/my-doc.md',
  title: 'My Document',
  audience: 'technical',        // Who it's for
  visibility: 'public',         // Who can access it
  // ...
}

2. Run security validation:

node scripts/validate-document-security.js "My Document" docs/my-doc.md

3. If validation passes, add to TECHNICAL_DOCS array:

const TECHNICAL_DOCS = [
  {
    file: 'docs/my-doc.md',
    visibility: 'public', // ✅ REQUIRED
    // ...
  }
];

4. Run import:

node scripts/import-technical-docs.js

For Developers: Deploying to Production

1. Verify no internal/confidential docs in import list:

grep -A 5 "visibility:" scripts/import-technical-docs.js

2. Run pre-action check:

node scripts/pre-action-check.js document-deployment "Deploy docs to production"

3. Check CrossReferenceValidator against inst_012:

• Are any documents marked 'internal' or 'confidential'?
• If yes → BLOCKED (requires explicit human approval)
• If no → Proceed

4. Deploy only after validation passes

Content Guidelines

Mark as visibility: 'public' if:

• General framework documentation
• API reference guides
• Implementation tutorials
• Case studies (anonymized)
• Blog posts

Mark as visibility: 'internal' if:

• Deployment procedures
• Infrastructure setup guides
• Team processes
• Internal roadmaps
• Non-sensitive financial data

Mark as visibility: 'confidential' if:

• Security audits or vulnerability reports
• API keys, secrets, credentials
• Payment processor setup (Stripe keys, etc.)
• Database connection strings
• Sensitive financial information
• Production environment details

---

Framework Integration

BoundaryEnforcer

Triggers on:

• Document import with visibility: 'internal' or visibility: 'confidential'
• Deployment scripts that include document operations

Required action:

• Verify inst_012 (no public deployment of sensitive docs)
• Require human approval if overriding

CrossReferenceValidator

Checks:

• Before document deployment: Scan for conflicts with inst_012
• Before modifying Document model: Verify visibility enforcement

MetacognitiveVerifier

Triggers on:

• Complex document operations (>3 files, multiple visibility levels)
• First-time deployment of new document categories

Required verification:

• "What are the security consequences of this deployment?"
• "Are there alternative approaches with lower risk?"
• "What validation steps are needed?"

---

Testing

Test Cases

1. Security Validation - Credentials

node scripts/validate-document-security.js "Test Doc" <(echo "stripe_secret_key=sk_live_123")
# Expected: ❌ BLOCKED

2. Security Validation - Vulnerabilities

node scripts/validate-document-security.js "Security Audit" <(echo "CVE-2024-1234 vulnerability found")
# Expected: ❌ BLOCKED

3. Import with Security Block

# Add doc with credentials and visibility: 'public' to TECHNICAL_DOCS
node scripts/import-technical-docs.js
# Expected: Document blocked, errors++

4. API Visibility Filter

curl "https://agenticgovernance.digital/api/documents?audience=technical"
# Expected: Only documents with visibility: 'public'

---

Recovery Procedures

If Sensitive Document Accidentally Deployed

1. Immediate removal:

ssh production
mongosh tractatus_prod --eval "db.documents.deleteOne({slug: 'sensitive-doc-slug'})"

2. Verify removal:

curl "https://agenticgovernance.digital/api/documents?limit=100" | jq '.documents[].title'

3. Update import script:

// Remove document from TECHNICAL_DOCS array
// OR change visibility to 'internal' or 'confidential'

4. Document incident:

• Add to instruction-history.json notes
• Update this governance document
• Review security classification keywords

---

Maintenance

Quarterly Review

Check:

• Security classification keywords still comprehensive?
• Any new document categories requiring governance?
• Framework components detecting document security issues?

After Security Incidents

Update:

• Add new keywords to SECURITY_KEYWORDS
• Review inst_012 for additional requirements
• Enhance validation logic if needed

---

References

• Document Model: src/models/Document.model.js
• Security Validation: scripts/validate-document-security.js
• Import Script: scripts/import-technical-docs.js
• Documents Controller: src/controllers/documents.controller.js
• Instruction: .claude/instruction-history.json (inst_012)
• Pre-Action Check: scripts/pre-action-check.js

---

Last Updated: 2025-10-08 Next Review: 2026-01-08