cipher-security 0.2.0__py3-none-any.whl

gateway/prompt.py

@@ -0,0 +1,165 @@
+# Copyright (c) 2026 defconxt. All rights reserved.
+# Licensed under AGPL-3.0 — see LICENSE file for details.
+"""System prompt assembly for CIPHER gateway.
+
+Provides:
+- load_base_prompt: reads CLAUDE.md and strips the Trigger Keywords section
+- assemble_system_prompt: composes full system prompt with mode-specific skill injection
+"""
+
+import logging
+import re
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Repo root resolution
+# ---------------------------------------------------------------------------
+
+def _find_repo_root(start: Path) -> Path:
+    """Walk upward from *start* until a directory containing pyproject.toml is found."""
+    for candidate in [start] + list(start.parents):
+        if (candidate / "pyproject.toml").exists():
+            return candidate
+    raise FileNotFoundError(
+        f"Could not locate repo root from {start!r} (no pyproject.toml found)"
+    )
+
+
+# Cached at module import time — resolved from this file's location.
+_MODULE_DIR = Path(__file__).resolve().parent
+try:
+    REPO_ROOT: Path = _find_repo_root(_MODULE_DIR)
+except FileNotFoundError:
+    REPO_ROOT = _MODULE_DIR.parent.parent  # best-effort fallback
+
+
+# ---------------------------------------------------------------------------
+# Keyword table stripping
+# ---------------------------------------------------------------------------
+
+# Matches from "#### Trigger Keywords" through the next horizontal rule or end of file.
+# Uses re.DOTALL so `.` spans newlines.
+_TRIGGER_KW_RE = re.compile(
+    r"####\s*Trigger Keywords.*?(?=\n---|\Z)",
+    re.DOTALL | re.IGNORECASE,
+)
+
+
+def load_base_prompt(repo_root: Path | None = None) -> str:
+    """Read CLAUDE.md and strip the Trigger Keywords section.
+
+    The keyword table is stripped so the LLM cannot override gateway mode
+    routing by seeing the trigger mapping. CIPHER identity, operating mode
+    definitions, output format specs, and all other content are preserved.
+
+    Args:
+        repo_root: Explicit repo root path. Defaults to the module-level REPO_ROOT.
+
+    Returns:
+        Stripped CLAUDE.md content as a string.
+    """
+    root = repo_root or REPO_ROOT
+    claude_md = root / "CLAUDE.md"
+
+    if not claude_md.exists():
+        logger.warning("load_base_prompt: CLAUDE.md not found at %s", claude_md)
+        return ""
+
+    text = claude_md.read_text(encoding="utf-8")
+    stripped = _TRIGGER_KW_RE.sub("", text)
+    # Collapse any triple+ blank lines left by the removal.
+    stripped = re.sub(r"\n{3,}", "\n\n", stripped).strip()
+    return stripped
+
+
+# ---------------------------------------------------------------------------
+# Skill map and loading
+# ---------------------------------------------------------------------------
+
+# Maps CIPHER mode names to SKILL.md paths relative to skills/.
+MODE_SKILL_MAP: dict[str, str] = {
+    "RED": "red-team/SKILL.md",
+    "BLUE": "blue-team/SKILL.md",
+    "PURPLE": "purple-team/SKILL.md",
+    "PRIVACY": "privacy-engineering/SKILL.md",
+    "RECON": "osint-recon/SKILL.md",
+    "INCIDENT": "incident-response/SKILL.md",
+    "ARCHITECT": "security-architecture/SKILL.md",
+}
+
+# Background layers injected per mode.
+# RED always gets PURPLE as background; ALL modes get PRIVACY.
+_BACKGROUND_LAYERS: dict[str, list[str]] = {
+    "RED": ["PURPLE", "PRIVACY"],
+}
+_DEFAULT_BACKGROUND: list[str] = ["PRIVACY"]
+
+
+def load_skill(mode: str, repo_root: Path | None = None) -> str:
+    """Load the SKILL.md file for *mode*.
+
+    Args:
+        mode: CIPHER mode name (e.g. "RED", "BLUE").
+        repo_root: Explicit repo root. Defaults to REPO_ROOT.
+
+    Returns:
+        SKILL.md contents, or empty string if mode unknown or file missing.
+    """
+    root = repo_root or REPO_ROOT
+    rel_path = MODE_SKILL_MAP.get(mode.upper())
+    if rel_path is None:
+        return ""
+
+    skill_file = root / "skills" / rel_path
+    if not skill_file.exists():
+        logger.warning("load_skill: skill file not found at %s", skill_file)
+        return ""
+
+    return skill_file.read_text(encoding="utf-8")
+
+
+def assemble_system_prompt(mode: str, repo_root: Path | None = None) -> str:
+    """Assemble the full CIPHER system prompt for *mode*.
+
+    Composition:
+    1. Base prompt (CLAUDE.md with keyword table stripped)
+    2. Primary skill for the requested mode
+    3. Background layers (PURPLE for RED; PRIVACY for all modes)
+
+    Sections are joined with ``\\n\\n---\\n\\n``. Empty sections are omitted.
+
+    Args:
+        mode: CIPHER operating mode (e.g. "RED", "BLUE", "ARCHITECT").
+        repo_root: Explicit repo root. Defaults to REPO_ROOT.
+
+    Returns:
+        Assembled system prompt string.
+    """
+    root = repo_root or REPO_ROOT
+    upper_mode = mode.upper()
+
+    sections: list[str] = []
+
+    # 1. Base prompt.
+    base = load_base_prompt(root)
+    if base:
+        sections.append(base)
+
+    # 2. Primary skill.
+    primary = load_skill(upper_mode, root)
+    if primary:
+        sections.append(primary)
+
+    # 3. Background layers.
+    backgrounds = _BACKGROUND_LAYERS.get(upper_mode, _DEFAULT_BACKGROUND)
+    for bg_mode in backgrounds:
+        if bg_mode == upper_mode:
+            # Never double-inject the primary skill.
+            continue
+        bg_skill = load_skill(bg_mode, root)
+        if bg_skill:
+            sections.append(bg_skill)
+
+    return "\n\n---\n\n".join(sections)

gateway/retriever.py

@@ -0,0 +1,257 @@
+# Copyright (c) 2026 defconxt. All rights reserved.
+# Licensed under AGPL-3.0 — see LICENSE file for details.
+"""CIPHER RAG retriever — semantic search over the knowledge base.
+
+Uses ChromaDB (embedded, persistent) to store and query document chunks.
+Chunks are split on markdown headers to preserve semantic boundaries.
+
+Usage:
+    from gateway.retriever import Retriever
+
+    retriever = Retriever()
+    chunks = retriever.query("Kerberos AS-REP roasting", top_k=5)
+    context = retriever.format_context(chunks)
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import chromadb
+
+from gateway.prompt import REPO_ROOT
+
+logger = logging.getLogger(__name__)
+
+# Default persistent storage location.
+_DEFAULT_DB_DIR = REPO_ROOT / ".chromadb"
+_COLLECTION_NAME = "cipher_knowledge"
+
+
+class Retriever:
+    """Semantic retriever over CIPHER knowledge base.
+
+    Wraps a ChromaDB persistent collection. On init, connects to the
+    existing store (or creates it if missing). Use ``ingest()`` to
+    populate or refresh the index from ``knowledge/`` files.
+    """
+
+    def __init__(self, db_dir: Path | None = None) -> None:
+        self._db_dir = db_dir or _DEFAULT_DB_DIR
+        self._client = chromadb.PersistentClient(path=str(self._db_dir))
+        self._collection = self._client.get_or_create_collection(
+            name=_COLLECTION_NAME,
+            metadata={"hnsw:space": "cosine"},
+        )
+        count = self._collection.count()
+        logger.info("Retriever: loaded collection %r (%d chunks)", _COLLECTION_NAME, count)
+
+    @property
+    def count(self) -> int:
+        """Number of chunks in the collection."""
+        return self._collection.count()
+
+    def query(self, text: str, top_k: int = 5) -> list[dict]:
+        """Retrieve the most relevant chunks for *text*.
+
+        Args:
+            text: Query string.
+            top_k: Maximum number of chunks to return.
+
+        Returns:
+            List of dicts with keys: document, source, distance.
+        """
+        if self._collection.count() == 0:
+            logger.warning("Retriever: collection is empty — run 'cipher-gw ingest' first")
+            return []
+
+        results = self._collection.query(
+            query_texts=[text],
+            n_results=min(top_k, self._collection.count()),
+        )
+
+        chunks: list[dict] = []
+        for i, doc in enumerate(results["documents"][0]):
+            meta = results["metadatas"][0][i]
+            dist = results["distances"][0][i] if results.get("distances") else None
+            chunks.append({
+                "document": doc,
+                "source": meta.get("source", "unknown"),
+                "section": meta.get("section", ""),
+                "distance": dist,
+            })
+        return chunks
+
+    @staticmethod
+    def format_context(chunks: list[dict], max_tokens_estimate: int = 6000) -> str:
+        """Format retrieved chunks into a context block for injection.
+
+        Estimates ~4 chars per token. Truncates to stay within budget.
+
+        Args:
+            chunks: List of chunk dicts from query().
+            max_tokens_estimate: Rough token budget for the context block.
+
+        Returns:
+            Formatted context string ready for system prompt injection.
+        """
+        if not chunks:
+            return ""
+
+        max_chars = max_tokens_estimate * 4
+        lines: list[str] = ["## Retrieved Knowledge Context\n"]
+        current_len = len(lines[0])
+
+        for chunk in chunks:
+            source = chunk["source"]
+            section = chunk.get("section", "")
+            header = f"### [{source}] {section}".strip()
+            entry = f"{header}\n{chunk['document']}\n"
+
+            if current_len + len(entry) > max_chars:
+                break
+
+            lines.append(entry)
+            current_len += len(entry)
+
+        return "\n".join(lines)
+
+    def ingest(
+        self,
+        knowledge_dir: Path | None = None,
+        chunk_size: int = 1500,
+        chunk_overlap: int = 200,
+    ) -> int:
+        """Ingest knowledge files into the vector store.
+
+        Clears the existing collection and re-indexes from scratch.
+
+        Args:
+            knowledge_dir: Path to knowledge/ directory. Defaults to REPO_ROOT/knowledge.
+            chunk_size: Target chunk size in characters.
+            chunk_overlap: Overlap between consecutive chunks in characters.
+
+        Returns:
+            Number of chunks indexed.
+        """
+        kb_dir = knowledge_dir or REPO_ROOT / "knowledge"
+        if not kb_dir.is_dir():
+            raise FileNotFoundError(f"Knowledge directory not found: {kb_dir}")
+
+        md_files = sorted(kb_dir.glob("*.md"))
+        if not md_files:
+            raise FileNotFoundError(f"No .md files found in {kb_dir}")
+
+        logger.info("Retriever: ingesting %d files from %s", len(md_files), kb_dir)
+
+        # Clear existing data.
+        self._client.delete_collection(_COLLECTION_NAME)
+        self._collection = self._client.get_or_create_collection(
+            name=_COLLECTION_NAME,
+            metadata={"hnsw:space": "cosine"},
+        )
+
+        total_chunks = 0
+        for md_file in md_files:
+            filename = md_file.name
+            text = md_file.read_text(encoding="utf-8")
+            chunks = _split_markdown(text, filename, chunk_size, chunk_overlap)
+
+            if not chunks:
+                continue
+
+            ids = [f"{filename}::{i}" for i in range(len(chunks))]
+            documents = [c["text"] for c in chunks]
+            metadatas = [{"source": c["source"], "section": c["section"]} for c in chunks]
+
+            # ChromaDB has a batch limit; add in batches of 500.
+            for batch_start in range(0, len(ids), 500):
+                batch_end = batch_start + 500
+                self._collection.add(
+                    ids=ids[batch_start:batch_end],
+                    documents=documents[batch_start:batch_end],
+                    metadatas=metadatas[batch_start:batch_end],
+                )
+
+            total_chunks += len(chunks)
+            logger.debug("  %s: %d chunks", filename, len(chunks))
+
+        logger.info("Retriever: ingested %d chunks from %d files", total_chunks, len(md_files))
+        return total_chunks
+
+
+def _split_markdown(
+    text: str,
+    filename: str,
+    chunk_size: int = 1500,
+    chunk_overlap: int = 200,
+) -> list[dict]:
+    """Split a markdown document into chunks on header boundaries.
+
+    Strategy:
+    1. Split on ## and ### headers (keeping higher-level context).
+    2. If a section exceeds chunk_size, split it further at paragraph
+       boundaries with overlap.
+    3. Each chunk carries its source filename and section header.
+
+    Args:
+        text: Full markdown text.
+        filename: Source filename for metadata.
+        chunk_size: Target chunk size in characters.
+        chunk_overlap: Overlap between chunks when splitting long sections.
+
+    Returns:
+        List of dicts with keys: text, source, section.
+    """
+    import re
+
+    chunks: list[dict] = []
+
+    # Split on markdown headers (## or ###), keeping the header with its section.
+    sections = re.split(r"(?=^#{1,3}\s)", text, flags=re.MULTILINE)
+
+    current_header = filename.replace(".md", "").replace("-", " ").title()
+
+    for section in sections:
+        section = section.strip()
+        if not section:
+            continue
+
+        # Extract section header if present.
+        header_match = re.match(r"^(#{1,3})\s+(.+)", section)
+        if header_match:
+            current_header = header_match.group(2).strip()
+
+        if len(section) <= chunk_size:
+            chunks.append({
+                "text": section,
+                "source": filename,
+                "section": current_header,
+            })
+        else:
+            # Split long sections at paragraph boundaries.
+            paragraphs = re.split(r"\n\n+", section)
+            buffer = ""
+            for para in paragraphs:
+                if buffer and len(buffer) + len(para) + 2 > chunk_size:
+                    chunks.append({
+                        "text": buffer.strip(),
+                        "source": filename,
+                        "section": current_header,
+                    })
+                    # Keep overlap from the end of the buffer.
+                    if chunk_overlap > 0:
+                        buffer = buffer[-chunk_overlap:] + "\n\n" + para
+                    else:
+                        buffer = para
+                else:
+                    buffer = buffer + "\n\n" + para if buffer else para
+
+            if buffer.strip():
+                chunks.append({
+                    "text": buffer.strip(),
+                    "source": filename,
+                    "section": current_header,
+                })
+
+    return chunks

gateway/theme.py

@@ -0,0 +1,91 @@
+# Copyright (c) 2026 defconxt. All rights reserved.
+# Licensed under AGPL-3.0 — see LICENSE file for details.
+"""CIPHER cyberpunk theme — colors, styles, and output helpers."""
+from __future__ import annotations
+
+from rich.console import Console
+from rich.theme import Theme
+
+# Cyberpunk color palette
+COLORS = {
+    "primary": "#00FF41",       # Matrix green
+    "secondary": "#0D0D0D",     # Near-black background
+    "accent": "#00E5CC",        # Cyan accent
+    "success": "#00E5CC",       # Cyan
+    "warning": "#FFB020",       # Amber
+    "error": "#FF4D4D",         # Coral red
+    "muted": "#5A6480",         # Dim gray
+    # Mode-specific
+    "mode.red": "#FF2D2D",      # Offensive
+    "mode.blue": "#2D9BFF",     # Defensive
+    "mode.purple": "#9B59B6",   # Detection engineering
+    "mode.privacy": "#27AE60",  # Privacy
+    "mode.recon": "#F39C12",    # OSINT
+    "mode.incident": "#E74C3C", # Incident response
+    "mode.architect": "#3498DB", # Architecture
+}
+
+MODE_COLORS: dict[str, str] = {
+    "RED": COLORS["mode.red"],
+    "BLUE": COLORS["mode.blue"],
+    "PURPLE": COLORS["mode.purple"],
+    "PRIVACY": COLORS["mode.privacy"],
+    "RECON": COLORS["mode.recon"],
+    "INCIDENT": COLORS["mode.incident"],
+    "ARCHITECT": COLORS["mode.architect"],
+}
+
+cipher_theme = Theme({
+    "cipher.primary": COLORS["primary"],
+    "cipher.accent": COLORS["accent"],
+    "cipher.success": COLORS["success"],
+    "cipher.warning": COLORS["warning"],
+    "cipher.error": COLORS["error"],
+    "cipher.muted": COLORS["muted"],
+    "cipher.mode.red": COLORS["mode.red"],
+    "cipher.mode.blue": COLORS["mode.blue"],
+    "cipher.mode.purple": COLORS["mode.purple"],
+    "cipher.mode.privacy": COLORS["mode.privacy"],
+    "cipher.mode.recon": COLORS["mode.recon"],
+    "cipher.mode.incident": COLORS["mode.incident"],
+    "cipher.mode.architect": COLORS["mode.architect"],
+})
+
+console = Console(theme=cipher_theme, highlight=False)
+err_console = Console(theme=cipher_theme, stderr=True, highlight=False)
+
+BANNER = r"""[cipher.primary]
+   ██████╗██╗██████╗ ██╗  ██╗███████╗██████╗
+  ██╔════╝██║██╔══██╗██║  ██║██╔════╝██╔══██╗
+  ██║     ██║██████╔╝███████║█████╗  ██████╔╝
+  ██║     ██║██╔═══╝ ██╔══██║██╔══╝  ██╔══██╗
+  ╚██████╗██║██║     ██║  ██║███████╗██║  ██║
+   ╚═════╝╚═╝╚═╝     ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝[/]
+  [cipher.muted]Security Engineering Assistant[/]
+"""
+
+
+def print_banner() -> None:
+    """Print the CIPHER ASCII banner."""
+    console.print(BANNER)
+
+
+def print_success(msg: str) -> None:
+    console.print(f"  [cipher.success]✓[/] {msg}")
+
+
+def print_error(msg: str) -> None:
+    console.print(f"  [cipher.error]✗[/] {msg}")
+
+
+def print_warn(msg: str) -> None:
+    console.print(f"  [cipher.warning]⚠[/] {msg}")
+
+
+def print_info(msg: str) -> None:
+    console.print(f"  [cipher.muted]●[/] {msg}")
+
+
+def mode_style(mode: str) -> str:
+    """Return the Rich style string for a CIPHER mode."""
+    return f"cipher.mode.{mode.lower()}" if f"cipher.mode.{mode.lower()}" in cipher_theme.styles else "cipher.primary"