git clone https://github.com/scriptedstatement/claude-ir.git
cd claude-ir
./setup.sh
claude

git clone https://github.com/scriptedstatement/forensic-rag-mcp.git
cd forensic-rag-mcp

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e .

# Build the index (fetches online sources, ~5 minutes first time)
python -m rag_mcp.build

# Check status
python -m rag_mcp.status

# Run MCP server (for Claude Code integration)
python -m rag_mcp.server

# Full build (fetch all sources)
python -m rag_mcp.build

# Use cached sources only (offline mode)
python -m rag_mcp.build --skip-online

# Force re-fetch all sources
python -m rag_mcp.build --force-fetch

# Preview what would be built
python -m rag_mcp.build --dry-run

# Check for updates and apply
python -m rag_mcp.refresh

# Check only (don't apply)
python -m rag_mcp.refresh --check-only

# Refresh specific source
python -m rag_mcp.refresh --source sigma

# Show status
python -m rag_mcp.status

# JSON output
python -m rag_mcp.status --json

# Skip update checks (faster)
python -m rag_mcp.status --no-check

knowledge/
├── my-playbook.md      # Markdown
├── ioc-list.txt        # Plain text
└── detections.jsonl    # JSONL records

# Ingest with friendly name
python -m rag_mcp.ingest /path/to/doc.txt --name "my-doc"

# List ingested documents
python -m rag_mcp.ingest --list

# Remove specific document
python -m rag_mcp.ingest --remove "my-doc"

# Remove all ingested
python -m rag_mcp.ingest --remove-all

# Filter by source
search(query="credential dumping", source="sigma")

# Filter by MITRE technique
search(query="persistence", technique="T1053")

# Filter by platform
search(query="privilege escalation", platform="windows")

{
  "mcpServers": {
    "rag-knowledge": {
      "command": "/path/to/forensic-rag-mcp/.venv/bin/python",
      "args": ["-m", "rag_mcp.server"],
      "cwd": "/path/to/forensic-rag-mcp",
      "env": {
        "PYTHONPATH": "/path/to/forensic-rag-mcp/src"
      }
    }
  }
}

rag-mcp/
├── src/rag_mcp/
│   ├── server.py      # MCP server
│   ├── index.py       # Search engine wrapper
│   ├── sources.py     # Online source management (23 sources)
│   ├── ingest.py      # User document processing
│   ├── build.py       # Full index builder
│   ├── refresh.py     # Incremental updates
│   ├── status.py      # Status reporting
│   ├── config.py      # Centralized configuration management
│   ├── fs_safety.py   # Filesystem safety guardrails
│   ├── constants.py   # Project-wide constants
│   └── utils.py       # Shared utilities
├── data/              # Built index (gitignored, users rebuild)
│   ├── chroma/        # ChromaDB vector store
│   ├── sources/       # Cached online source JSONL
│   └── *.json         # State files
├── knowledge/         # User documents - .txt, .md, .json, .jsonl (watched folder)
└── tests/             # Test suite

# In your logging configuration
import logging

# Create handlers FIRST
metrics_handler = logging.FileHandler("logs/query_metrics.log")
attention_handler = logging.FileHandler("logs/attention.log")

# Get loggers and add handlers (this enables logging)
metrics_logger = logging.getLogger("rag_mcp.query_metrics")
metrics_logger.setLevel(logging.INFO)
metrics_logger.addHandler(metrics_handler)
metrics_logger.propagate = True  # Enable propagation if you want console output too

attention_logger = logging.getLogger("rag_mcp.attention")
attention_logger.setLevel(logging.WARNING)
attention_logger.addHandler(attention_handler)
attention_logger.propagate = True

# Full interactive workflow (analyze, recommend, approve)
python -m rag_mcp.analyze_queries

# Just view report without making changes
python -m rag_mcp.analyze_queries --report-only

# Analyze last 7 days only
python -m rag_mcp.analyze_queries --since 7d

# Set approver name for audit trail
python -m rag_mcp.analyze_queries --approver "your-name"

# Export analysis to JSON
python -m rag_mcp.analyze_queries --export analysis.json

$ python -m rag_mcp.analyze_queries
Analyzing query logs...

======================================================================
RAG QUERY ANALYSIS REPORT
======================================================================
Period: 2026-01-15 08:00 to 2026-02-02 10:30
Total queries analyzed: 1523

----------------------------------------------------------------------
QUERY TYPE STATISTICS
----------------------------------------------------------------------
Type              Count      Avg      P25      Min     Low%
----------------------------------------------------------------------
general             892    0.712    0.645    0.412     8.2%
mitre_id            456    0.789    0.715    0.521     3.1%
detection           175    0.698    0.621    0.445    12.0%

======================================================================
RECOMMENDATIONS
======================================================================

[1] Lower detection threshold from 0.55 to 0.52
    Type: threshold
    Confidence: medium
    Affected queries: 21
    Rationale: 12.0% of 175 queries scored below current threshold.

----------------------------------------------------------------------
APPROVAL REQUIRED
----------------------------------------------------------------------
[1/1] Lower detection threshold from 0.55 to 0.52
  Rationale: 12.0% of 175 queries scored below current threshold.
  Change: 0.55 -> 0.52
  Confidence: medium

  Approve? [Y/N/Q]: y
  -> APPROVED

1 change(s) applied and saved to tuning_config.json

{
  "version": "1.0",
  "thresholds": {
    "general": 0.50,
    "mitre_id": 0.55,
    "detection": 0.52,
    "forensic": 0.55
  },
  "source_boosts": {
    "forensic_clarifications": 1.15
  },
  "keyword_boost": 1.15,
  "last_modified": "2026-02-02T10:45:00",
  "last_modified_by": "analyst",
  "modification_history": [...]
}

# Create a Fine-grained Personal Access Token with:
# - Public Repositories (read-only) - NO other permissions needed
# - No access to private repositories
# - No write permissions

export GITHUB_TOKEN="github_pat_..."

# Install pip-audit
pip install pip-audit

# Scan for vulnerabilities
pip-audit

# Or with requirements file
pip-audit -r requirements.txt