🔒 How-To: Security Analysis and Content Protection

Goal: Detect sensitive content, implement security controls, and ensure safe architectural documentation.

When to use this guide: Before sharing code, documentation, or architectural decisions; when implementing security controls; during security audits.

🚨 Quick Security Scan

Scan Content for Secrets

Most Common Use Case: Check if content contains API keys, passwords, or sensitive data before sharing.

{
  "tool": "analyze_content_security",
  "parameters": {
    "content": "const apiKey = 'sk-1234567890abcdef'; // Your code here",
    "enhancedMode": true,
    "enableTreeSitterAnalysis": true
  }
}

Expected Result:

{
  "securityIssues": [
    {
      "type": "api_key",
      "severity": "high",
      "line": 1,
      "pattern": "sk-1234567890abcdef",
      "recommendation": "Replace with environment variable"
    }
  ],
  "riskLevel": "high",
  "maskingRecommended": true
}

Auto-Mask Sensitive Content

{
  "tool": "generate_content_masking",
  "parameters": {
    "content": "const apiKey = 'sk-1234567890abcdef';",
    "maskingLevel": "strict",
    "preserveStructure": true
  }
}

Result:

const apiKey = 'sk-xxxxxxxxxxxxxxxx';

🔍 Comprehensive Security Analysis

Project-Wide Security Scan

Use Case: Audit entire project for security issues before deployment or code review.

{
  "tool": "analyze_project_ecosystem",
  "parameters": {
    "projectPath": ".",
    "securityFocused": true,
    "includeEnvironment": true,
    "enhancedMode": true
  }
}

What it finds:

Hardcoded credentials in source code
Insecure configuration patterns
Exposed sensitive files
Security anti-patterns in architecture
Dependency vulnerabilities (basic detection)

Environment-Specific Security Analysis

{
  "tool": "analyze_environment",
  "parameters": {
    "includeSecurityAnalysis": true,
    "checkContainerization": true,
    "validateDeploymentSecurity": true
  }
}

Detects:

Insecure environment variable patterns
Container security misconfigurations
Deployment security gaps
Infrastructure security issues

🛡️ Content Masking Strategies

Basic Masking (Quick Protection)

{
  "tool": "generate_content_masking",
  "parameters": {
    "content": "Your content with secrets",
    "maskingLevel": "moderate",
    "preserveStructure": true
  }
}

Masking Levels:

lenient: Only obvious secrets (API keys, passwords)
moderate: Common sensitive patterns (default)
strict: Aggressive masking including potential PII

Advanced Masking (Custom Patterns)

{
  "tool": "generate_content_masking",
  "parameters": {
    "content": "Company internal token: COMP_12345_SECRET",
    "maskingLevel": "strict",
    "userDefinedPatterns": ["COMP_[0-9]+_[A-Z]+", "internal-.*-token"],
    "preserveStructure": true,
    "includeLineNumbers": true
  }
}

Validate Masking Quality

{
  "tool": "validate_content_masking",
  "parameters": {
    "originalContent": "const key = 'secret123';",
    "maskedContent": "const key = 'xxxxxx';",
    "strictValidation": true
  }
}

Checks:

No sensitive data leaked through masking
Code structure preserved
Functionality not broken by masking
Masking consistency across similar patterns

🔐 Security Pattern Detection

Common Security Anti-Patterns

The server automatically detects these security issues:

Credential Exposure

// ❌ Detected as security issue
const apiKey = 'sk-1234567890abcdef';
const password = 'mypassword123';
const token = 'ghp_xxxxxxxxxxxxxxxxxxxx';

// ✅ Secure pattern
const apiKey = process.env.API_KEY;

Insecure Configuration

# ❌ Detected as security issue
database:
  password: "plaintext_password"
  ssl: false

# ✅ Secure pattern
database:
  password: ${DB_PASSWORD}
  ssl: true

Exposed Sensitive Files

{
  "tool": "analyze_content_security",
  "parameters": {
    "content": "Check if .env files are in git",
    "contentType": "configuration",
    "checkFilePatterns": true
  }
}

Detects:

.env files in version control
Private keys in repositories
Configuration files with secrets
Backup files with sensitive data

Custom Security Rules

{
  "tool": "generate_rules",
  "parameters": {
    "source": "security_focused",
    "projectPath": ".",
    "customPatterns": [
      {
        "name": "company_secrets",
        "pattern": "COMPANY_[A-Z_]+",
        "severity": "high",
        "description": "Company-specific secret pattern"
      }
    ]
  }
}

🏢 Enterprise Security Workflows

Security-First ADR Generation

Use Case: Generate ADRs that include security considerations from the start.

{
  "tool": "suggest_adrs",
  "parameters": {
    "projectPath": ".",
    "securityFocused": true,
    "includeSecurityDecisions": true,
    "analysisScope": "security"
  }
}

Generates ADRs for:

Authentication and authorization strategies
Data encryption decisions
Security monitoring approaches
Incident response procedures
Compliance requirements

Security Compliance Validation

{
  "tool": "validate_adr_bootstrap",
  "parameters": {
    "adrDirectory": "./adrs",
    "complianceFramework": "security",
    "enableTreeSitterAnalysis": true
  }
}

Validates:

Security decisions are documented
Implementation matches security ADRs
No security anti-patterns in code
Compliance with security standards

Deployment Security Readiness

{
  "tool": "deployment_readiness",
  "parameters": {
    "operation": "security_audit",
    "projectPath": ".",
    "securityValidation": true,
    "enableTreeSitterAnalysis": true
  }
}

Security Checks:

No hardcoded secrets in deployment artifacts
Security configurations validated
Container security best practices
Infrastructure security compliance

🔧 Integration with Security Tools

Pre-Commit Security Hooks

Add to your .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: mcp-security-scan
        name: MCP Security Analysis
        entry: mcp-security-scan.sh
        language: script
        files: \.(ts|js|py|yaml|yml|json)$

Create mcp-security-scan.sh:

#!/bin/bash
# Use MCP server for security scanning
echo "Running MCP security analysis..."

# Scan staged files for security issues
git diff --cached --name-only | while read file; do
  if [[ -f "$file" ]]; then
    content=$(cat "$file")
    # Use MCP tool to analyze content
    # (Implementation depends on your MCP client setup)
  fi
done

CI/CD Security Integration

GitHub Actions Example:

name: Security Analysis
on: [push, pull_request]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup MCP Server
        run: npm install -g mcp-adr-analysis-server
      - name: Run Security Analysis
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
          PROJECT_PATH: ${{ github.workspace }}
          EXECUTION_MODE: full
        run: |
          # Run security analysis via MCP
          # (Implementation depends on your CI setup)

🎯 Security Best Practices

Content Preparation

Before Analysis:

Never analyze production secrets - use test/example data
Use environment variables for real credentials
Sanitize logs and outputs before sharing
Review masked content before distribution

Masking Guidelines

What to Always Mask:

API keys and tokens
Passwords and passphrases
Private keys and certificates
Database connection strings
Internal URLs and endpoints
Personal identifiable information (PII)

What to Consider Masking:

Internal project names
Server hostnames
File paths with usernames
Email addresses
Phone numbers

Validation Checklist

Before sharing any content:

{
  "tool": "analyze_content_security",
  "parameters": {
    "content": "your final content",
    "enhancedMode": true,
    "strictValidation": true,
    "enableTreeSitterAnalysis": true
  }
}

Verify:

✅ No sensitive patterns detected
✅ Masking preserves functionality
✅ No information leakage through context
✅ Compliance with security policies

🚨 Incident Response

Suspected Secret Exposure

If you accidentally exposed secrets:

Immediate Assessment

{
  "tool": "analyze_content_security",
  "parameters": {
    "content": "suspected exposed content",
    "enhancedMode": true,
    "urgentMode": true
  }
}

Generate Incident Report

{
  "tool": "generate_security_incident_report",
  "parameters": {
    "incidentType": "credential_exposure",
    "affectedContent": "description of what was exposed",
    "timeline": "when exposure occurred"
  }
}

Remediation Steps

Rotate exposed credentials immediately
Review access logs for unauthorized usage
Update security patterns to prevent recurrence
Document lessons learned in ADRs

False Positive Handling

When security tools flag legitimate content:

{
  "tool": "configure_security_whitelist",
  "parameters": {
    "projectPath": ".",
    "whitelistPatterns": ["example-api-key-.*", "test-token-.*", "demo-secret-.*"],
    "justification": "These are example/test patterns, not real secrets"
  }
}

📊 Security Metrics and Reporting

Security Dashboard

{
  "tool": "generate_security_dashboard",
  "parameters": {
    "projectPath": ".",
    "includeMetrics": true,
    "timeframe": "last_30_days"
  }
}

Tracks:

Security issues found and resolved
Masking operations performed
Security ADR compliance
Trend analysis over time

Compliance Reporting

{
  "tool": "generate_compliance_report",
  "parameters": {
    "framework": "SOC2", // or "GDPR", "HIPAA", etc.
    "projectPath": ".",
    "includeEvidence": true
  }
}

Environment Configuration - Security-related environment variables
Deployment Readiness - Security validation before deployment
Troubleshooting - Security-related issues and solutions
API Reference - Complete security tool documentation

Security concern not covered here? → File a Security Issue for sensitive matters or General Issue for questions.

🚨 Quick Security Scan​

Scan Content for Secrets​

Auto-Mask Sensitive Content​

🔍 Comprehensive Security Analysis​

Project-Wide Security Scan​

Environment-Specific Security Analysis​

🛡️ Content Masking Strategies​

Basic Masking (Quick Protection)​

Advanced Masking (Custom Patterns)​

Validate Masking Quality​

🔐 Security Pattern Detection​

Common Security Anti-Patterns​

Credential Exposure​

Insecure Configuration​

Exposed Sensitive Files​

Custom Security Rules​

🏢 Enterprise Security Workflows​

Security-First ADR Generation​

Security Compliance Validation​

Deployment Security Readiness​

🔧 Integration with Security Tools​

Pre-Commit Security Hooks​

CI/CD Security Integration​

🎯 Security Best Practices​

Content Preparation​

Masking Guidelines​

Validation Checklist​

🚨 Incident Response​

Suspected Secret Exposure​

False Positive Handling​

📊 Security Metrics and Reporting​

Security Dashboard​

Compliance Reporting​

🔗 Related Documentation​