security-controls-mcp 0.2.0__py3-none-any.whl

security_controls_mcp/data_loader.py

@@ -0,0 +1,180 @@
+"""Data loader for SCF controls and framework mappings."""
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+class SCFData:
+    """Loads and provides access to SCF control data."""
+
+    def __init__(self):
+        self.controls: list[dict[str, Any]] = []
+        self.controls_by_id: dict[str, dict[str, Any]] = {}
+        self.framework_to_scf: dict[str, dict[str, list[str]]] = {}
+        self.frameworks: dict[str, dict[str, Any]] = {}
+        self._load_data()
+
+    def _load_data(self):
+        """Load SCF controls and reverse index from JSON files."""
+        data_dir = Path(__file__).parent / "data"
+
+        # Load controls
+        with open(data_dir / "scf-controls.json", "r", encoding="utf-8") as f:
+            data = json.load(f)
+            self.controls = data["controls"]
+
+        # Build ID index
+        self.controls_by_id = {ctrl["id"]: ctrl for ctrl in self.controls}
+
+        # Load reverse index
+        with open(data_dir / "framework-to-scf.json", "r", encoding="utf-8") as f:
+            self.framework_to_scf = json.load(f)
+
+        # Build framework metadata
+        self._build_framework_metadata()
+
+    def _build_framework_metadata(self):
+        """Build framework metadata from controls."""
+        # Framework display names (keys must match actual data which uses dots in version numbers)
+        framework_names = {
+            "nist_csf_2.0": "NIST Cybersecurity Framework 2.0",
+            "nist_800_53_r5": "NIST SP 800-53 Revision 5",
+            "iso_27001_2022": "ISO/IEC 27001:2022",
+            "iso_27002_2022": "ISO/IEC 27002:2022",
+            "cis_csc_8.1": "CIS Critical Security Controls v8.1",
+            "pci_dss_4.0.1": "PCI DSS v4.0.1",
+            "cmmc_2.0_level_1": "CMMC 2.0 Level 1",
+            "cmmc_2.0_level_2": "CMMC 2.0 Level 2",
+            "soc_2_tsc": "SOC 2 (TSC 2017:2022)",
+            "dora": "Digital Operational Resilience Act (DORA)",
+            "nis2": "Network and Information Security Directive (NIS2)",
+            "gdpr": "General Data Protection Regulation (GDPR)",
+            "ncsc_caf_4.0": "NCSC Cyber Assessment Framework 4.0",
+            "uk_cyber_essentials": "UK Cyber Essentials",
+            "fedramp_r5_moderate": "FedRAMP Revision 5 (Moderate)",
+            "hipaa_security_rule": "HIPAA Security Rule",
+        }
+
+        # Count controls per framework
+        for fw_key, fw_name in framework_names.items():
+            count = sum(1 for ctrl in self.controls if ctrl["framework_mappings"].get(fw_key))
+            self.frameworks[fw_key] = {
+                "key": fw_key,
+                "name": fw_name,
+                "controls_mapped": count,
+            }
+
+    def get_control(self, control_id: str) -> dict[str, Any] | None:
+        """Get control by SCF ID."""
+        return self.controls_by_id.get(control_id)
+
+    def search_controls(
+        self, query: str, frameworks: list[str] | None = None, limit: int = 10
+    ) -> list[dict[str, Any]]:
+        """Search controls by description. Case-insensitive string matching for v1."""
+        query_lower = query.lower()
+        results = []
+
+        for ctrl in self.controls:
+            # Check if query matches name or description (case-insensitive)
+            name_lower = ctrl["name"].lower() if ctrl["name"] else ""
+            desc_lower = ctrl["description"].lower() if ctrl["description"] else ""
+
+            if query_lower in name_lower or query_lower in desc_lower:
+                # Filter by frameworks if specified
+                if frameworks:
+                    has_mapping = any(ctrl["framework_mappings"].get(fw) for fw in frameworks)
+                    if not has_mapping:
+                        continue
+
+                # Get mapped frameworks for response
+                mapped_frameworks = [
+                    fw for fw, mappings in ctrl["framework_mappings"].items() if mappings
+                ]
+
+                # Create snippet (simple version - first 150 chars with highlight)
+                desc = ctrl["description"]
+                idx = desc.lower().find(query_lower)
+                if idx >= 0:
+                    start = max(0, idx - 50)
+                    end = min(len(desc), idx + len(query) + 100)
+                    snippet = desc[start:end]
+                    if start > 0:
+                        snippet = "..." + snippet
+                    if end < len(desc):
+                        snippet = snippet + "..."
+                else:
+                    snippet = desc[:150] + "..." if len(desc) > 150 else desc
+
+                results.append(
+                    {
+                        "control_id": ctrl["id"],
+                        "name": ctrl["name"],
+                        "snippet": snippet,
+                        "relevance": 1.0,  # Simple scoring for v1
+                        "mapped_frameworks": mapped_frameworks,
+                    }
+                )
+
+                if len(results) >= limit:
+                    break
+
+        return results
+
+    def get_framework_controls(
+        self, framework: str, include_descriptions: bool = False
+    ) -> list[dict[str, Any]]:
+        """Get all controls that map to a framework."""
+        results = []
+
+        for ctrl in self.controls:
+            fw_mappings = ctrl["framework_mappings"].get(framework)
+            if fw_mappings:
+                result = {
+                    "scf_id": ctrl["id"],
+                    "scf_name": ctrl["name"],
+                    "framework_control_ids": fw_mappings,
+                    "weight": ctrl["weight"],
+                }
+
+                if include_descriptions:
+                    result["description"] = ctrl["description"]
+
+                results.append(result)
+
+        return results
+
+    def map_frameworks(
+        self,
+        source_framework: str,
+        target_framework: str,
+        source_control: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """Map controls between two frameworks via SCF."""
+        results = []
+
+        # If source_control specified, filter to only controls with that mapping
+        for ctrl in self.controls:
+            source_mappings = ctrl["framework_mappings"].get(source_framework)
+            target_mappings = ctrl["framework_mappings"].get(target_framework)
+
+            # Skip if no source mapping
+            if not source_mappings:
+                continue
+
+            # Filter by source_control if specified
+            if source_control and source_control not in source_mappings:
+                continue
+
+            results.append(
+                {
+                    "scf_id": ctrl["id"],
+                    "scf_name": ctrl["name"],
+                    "source_controls": source_mappings,
+                    "target_controls": target_mappings or [],
+                    "weight": ctrl["weight"],
+                }
+            )
+
+        return results

security_controls_mcp/extractors/__init__.py

@@ -0,0 +1,5 @@
+"""Extractors for importing security standards from PDF files."""
+
+from .pdf_extractor import extract_standard
+
+__all__ = ["extract_standard"]

security_controls_mcp/extractors/pdf_extractor.py

@@ -0,0 +1,248 @@
+"""PDF extraction for security standards."""
+
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List
+
+import pdfplumber
+
+
+def extract_standard(
+    pdf_path: Path,
+    standard_id: str,
+    title: str,
+    version: str,
+    purchased_from: str,
+    purchase_date: str,
+) -> Dict[str, Any]:
+    """Extract a standard from PDF.
+
+    Args:
+        pdf_path: Path to PDF file
+        standard_id: Unique identifier for the standard
+        title: Full title of the standard
+        version: Version string
+        purchased_from: Where it was purchased
+        purchase_date: When it was purchased
+
+    Returns:
+        Dictionary with metadata and structure
+    """
+    # Open PDF and extract text
+    with pdfplumber.open(pdf_path) as pdf:
+        total_pages = len(pdf.pages)
+
+        # Extract text from all pages
+        pages_text = []
+        for page_num, page in enumerate(pdf.pages, start=1):
+            text = page.extract_text() or ""
+            pages_text.append({"page": page_num, "text": text})
+
+    # Detect structure
+    sections = _detect_sections(pages_text)
+    annexes = _detect_annexes(pages_text)
+
+    # Build metadata
+    metadata = {
+        "standard_id": standard_id,
+        "title": title,
+        "version": version,
+        "purchased_from": purchased_from,
+        "purchase_date": purchase_date,
+        "imported_date": datetime.now().isoformat(),
+        "license": "Proprietary - Licensed to individual user",
+        "pages": total_pages,
+        "restrictions": [
+            "Personal use only",
+            "No redistribution",
+            "No derivative works without permission",
+        ],
+    }
+
+    # Build structure
+    structure = {
+        "metadata": metadata,
+        "sections": sections,
+        "annexes": annexes,
+    }
+
+    # Calculate stats
+    total_clauses = len(sections)
+    for annex in annexes:
+        total_clauses += len(annex.get("controls", []))
+
+    stats = {
+        "pages": total_pages,
+        "sections": len(sections),
+        "annexes": len(annexes),
+        "total_clauses": total_clauses,
+    }
+
+    return {"metadata": metadata, "structure": structure, "stats": stats}
+
+
+def _detect_sections(pages_text: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Detect main sections in the document.
+
+    This uses heuristics to identify section headings like:
+    - "1 Scope"
+    - "5.1.2 Cryptographic controls"
+    - "Chapter 3: Requirements"
+    """
+    sections = []
+
+    # Common section patterns
+    # Matches: "1 Title", "1.2 Title", "1.2.3 Title"
+    section_pattern = re.compile(r"^(\d+(?:\.\d+)*)\s+([A-Z][^\n]{5,80})$", re.MULTILINE)
+
+    for page_info in pages_text:
+        page_num = page_info["page"]
+        text = page_info["text"]
+
+        # Find all section headers on this page
+        matches = section_pattern.finditer(text)
+
+        for match in matches:
+            section_id = match.group(1)
+            section_title = match.group(2).strip()
+
+            # Extract content until next section or end of page
+            start_pos = match.end()
+            next_match = section_pattern.search(text, start_pos)
+
+            if next_match:
+                content = text[start_pos : next_match.start()].strip()
+            else:
+                content = text[start_pos:].strip()
+
+            # Only include if we have meaningful content
+            if content and len(content) > 20:
+                sections.append(
+                    {
+                        "id": section_id,
+                        "title": section_title,
+                        "page": page_num,
+                        "content": content[:2000],  # Limit length
+                        "subsections": [],
+                    }
+                )
+
+    # Build hierarchy (nest subsections)
+    sections = _build_hierarchy(sections)
+
+    return sections
+
+
+def _detect_annexes(pages_text: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Detect annexes (like Annex A in ISO 27001).
+
+    Annexes often contain control listings with IDs like:
+    - "A.5.15 Access control"
+    - "Annex B.2.1 Requirements"
+    """
+    annexes = []
+
+    # Pattern for annex headers
+    annex_pattern = re.compile(r"^Annex\s+([A-Z])[:\s]+([^\n]+)$", re.MULTILINE | re.IGNORECASE)
+
+    # Pattern for controls within annexes
+    control_pattern = re.compile(r"^([A-Z]\.\d+(?:\.\d+)*)\s+([A-Z][^\n]{5,80})$", re.MULTILINE)
+
+    current_annex = None
+
+    for page_info in pages_text:
+        page_num = page_info["page"]
+        text = page_info["text"]
+
+        # Check for new annex
+        annex_match = annex_pattern.search(text)
+        if annex_match:
+            # Save previous annex if exists
+            if current_annex:
+                annexes.append(current_annex)
+
+            # Start new annex
+            annex_id = annex_match.group(1)
+            annex_title = annex_match.group(2).strip()
+            current_annex = {
+                "id": annex_id,
+                "title": annex_title,
+                "page": page_num,
+                "controls": [],
+            }
+
+        # If we're in an annex, look for controls
+        if current_annex:
+            control_matches = control_pattern.finditer(text)
+
+            for match in control_matches:
+                control_id = match.group(1)
+                control_title = match.group(2).strip()
+
+                # Extract content
+                start_pos = match.end()
+                next_match = control_pattern.search(text, start_pos)
+
+                if next_match:
+                    content = text[start_pos : next_match.start()].strip()
+                else:
+                    content = text[start_pos:].strip()
+
+                if content and len(content) > 10:
+                    current_annex["controls"].append(
+                        {
+                            "id": control_id,
+                            "title": control_title,
+                            "content": content[:1000],
+                            "page": page_num,
+                            "category": f"Annex {current_annex['id']}",
+                            "type": "normative",
+                        }
+                    )
+
+    # Add final annex
+    if current_annex and current_annex["controls"]:
+        annexes.append(current_annex)
+
+    return annexes
+
+
+def _build_hierarchy(sections: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Build hierarchical structure from flat section list.
+
+    Converts:
+        [{"id": "1"}, {"id": "1.1"}, {"id": "1.2"}, {"id": "2"}]
+    Into:
+        [{"id": "1", "subsections": [{"id": "1.1"}, {"id": "1.2"}]}, {"id": "2"}]
+    """
+    if not sections:
+        return []
+
+    # Build a tree structure
+    root = []
+    stack = []  # Stack of (section, level)
+
+    for section in sections:
+        section_id = section["id"]
+        level = section_id.count(".")
+
+        # Remove subsections key to avoid duplication
+        section = {k: v for k, v in section.items() if k != "subsections"}
+        section["subsections"] = []
+
+        # Pop stack until we find the parent level
+        while stack and stack[-1][1] >= level:
+            stack.pop()
+
+        if not stack:
+            # Top level section
+            root.append(section)
+            stack.append((section, level))
+        else:
+            # Add as subsection of parent
+            parent = stack[-1][0]
+            parent["subsections"].append(section)
+            stack.append((section, level))
+
+    return root