SecResearch CLI & Agent Skill

100% Free, Elite Open-Access Cybersecurity Research Engine for AI Agents & Security Analysts
Access peer-reviewed papers, zero-days, post-quantum cryptography, and NIST standards directly from the terminal or as an AI Agent Skill.

---

Overview

AI agents (Claude, Codex, Antigravity, Cursor, OpenAI Swarm) often struggle to find authentic, high-grade technical research on vulnerabilities, hardware exploits, malware analysis, or cryptographic algorithms because general search engines return SEO marketing blogs or paywalled IEEE/ACM links.

SecResearch solves this by providing a unified, token-optimized research interface to the world's 5 top Open Access cybersecurity repositories:

1. USENIX Security Symposium: Elite hardware, kernel, exploits, side-channels, and zero-day research with PDFs, presentation slides, and conference videos.
2. NDSS Symposium (Network and Distributed System Security): Premier venue for network protocols, distributed systems, malware evasion, and IoT/firmware security.
3. IACR Cryptology ePrint Archive: The global authority on post-quantum crypto (lattice, isogeny), zero-knowledge proofs, and cryptanalysis.
4. arXiv (cs.CR - Cryptography and Security): Real-time preprints on AI security, LLM jailbreak mitigations, and bleeding-edge exploits before formal journal release.
5. NIST CSRC (Computer Security Resource Center): US Federal standards, SP 800-series (SP 800-53, SP 800-207 Zero Trust), FIPS standards, and threat mitigation frameworks.

---

Architecture: Tri-Layer Design

SecResearch is designed with an ultra-efficient Tri-Layer Architecture:

flowchart TD
    UserReq["User / Agent Request"] --> Router{"Access Method"}
    
    Router -->|"1. Progressive Disclosure (~30 tokens idle)"| Skill["Agent Skill (cybersec-research)"]
    Router -->|"2. Direct Terminal / Script"| CLI["SecResearch CLI"]
    Router -->|"3. Legacy MCP Client"| MCP["FastMCP Server (sec-research mcp)"]
    
    Skill --> CLI
    MCP --> CLI
    
    CLI --> Dispatcher["Parallel Async Provider Layer"]
    Dispatcher --> P1["USENIX Security Provider"]
    Dispatcher --> P2["NDSS Symposium Provider"]
    Dispatcher --> P3["IACR Cryptology ePrint Provider"]
    Dispatcher --> P4["arXiv cs.CR Provider"]
    Dispatcher --> P5["NIST CSRC Provider"]
    
    CLI --> PDFEngine["PyMuPDF 2-Column Parser"]
    CLI --> Cache["SQLite FTS5 Local Cache"]
    
    PDFEngine --> TokenOpt["Token Budget & Section Extractor"]
    TokenOpt --> Output["Structured Markdown / JSON"]

Why Agent Skills over MCP?

• MCP Tool Tax: Standard MCP servers inject thousands of tokens of JSON Schema into the LLM context on every turn (~2,500 tokens/msg = 50,000+ wasted tokens in a 20-turn session).
• Skill Progressive Disclosure: The cybersec-research skill consumes only ~30 tokens in idle state. The LLM only invokes the CLI when a research task is requested.

---

Quick Start

Installation

Using uv (recommended, sub-second execution):

# Run directly without installing into global environment:
uvx --from . sec-research --help

# Or install in editable mode:
pip install -e .

---

CLI Usage Guide

1. Unified Multi-Source Search

Search all 5 repositories concurrently in <350ms:

sec-research search "Rowhammer DRAM exploit" --limit 5

Filter by specific sources:

sec-research search "post-quantum lattice signature" --source iacr,nist --limit 3

Format for AI Agents (--format json or --format markdown):

sec-research search "BGP route hijacking" --source ndss,arxiv --format markdown

2. Dedicated Venue Commands

# USENIX Security Symposium
sec-research usenix "hardware fault injection" --year 2024

# NDSS Symposium
sec-research ndss "malware dynamic analysis"

# IACR Cryptology ePrint
sec-research iacr "Kyber Dilithium FIPS 204"

# arXiv cs.CR
sec-research arxiv "LLM prompt injection defense"

# NIST CSRC Standards & Publications
sec-research nist "SP 800-207 Zero Trust"
sec-research nist "FIPS 140-3"

3. Smart Section Extraction (Token-Optimized)

Instead of dumping a 30-page PDF (~30,000 tokens), extract only the high-signal sections:

# Extract abstract and threat model:
sec-research get "https://arxiv.org/abs/2401.12345" --section "abstract,threat model"

# Extract countermeasures / mitigations:
sec-research get "https://eprint.iacr.org/2024/1365.pdf" --section "mitigations,conclusion"

# Download complete PDF to local disk:
sec-research get "https://arxiv.org/abs/2401.12345" --download ./paper.pdf

4. Local Offline Cache & Full-Text Search (FTS5)

Search previously queried papers and downloaded PDFs without any internet connection:

# View storage size and cache stats:
sec-research cache --stats

# Instant offline full-text search:
sec-research cache "Rowhammer"

---

Development & Testing

To install development dependencies and run the complete automated test suite:

# Install with dev dependencies:
pip install -e ".[dev]"

# Run all 16 unit and integration tests:
pytest -v

---

Using as an AI Agent Skill

Install the skill into your AI coding agent with a single command:

# Antigravity / Gemini CLI:
sec-research setup --agent antigravity

# Claude Code:
sec-research setup --agent claude

# Cursor IDE:
sec-research setup --agent cursor

# Install for all detected agents:
sec-research setup --agent all

Or manually link the skills/cybersec-research directory:

• Antigravity / Gemini CLI: ~/.agents/skills/cybersec-research/ or ~/.gemini/skills/
• Claude Code: ~/.claude/skills/cybersec-research/
• Cursor: .cursor/rules/cybersec-research.mdc

---

Optional MCP Server Mode

For environments where MCP is the only available integration (e.g., Claude Desktop):

sec-research mcp

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "sec-research": {
      "command": "uvx",
      "args": ["sec-research", "mcp"]
    }
  }
}

---

Project Structure

sec-research/
├── pyproject.toml               # Modern packaging with uv/hatchling
├── README.md                    # This documentation
├── LICENSE                      # MIT License
├── SECURITY.md                  # Vulnerability disclosure & ethical access policy
├── CONTRIBUTING.md              # Developer contribution guidelines
├── .github/
│   ├── workflows/ci.yml         # Multi-OS test matrix pipeline
│   ├── workflows/release.yml    # Automated release & PyPI publishing
│   └── ISSUE_TEMPLATE/          # Bug & feature templates
├── docs/
│   ├── ARCHITECTURE.md          # Technical design & token optimization
│   ├── PROVIDERS.md             # Provider APIs and scraping strategies
│   ├── AGENT_INTEGRATION.md     # How AI agents consume SecResearch
│   └── MCP.md                   # Dedicated MCP Server configuration & tools reference
├── skills/
│   └── cybersec-research/
│       └── SKILL.md             # Single Source of Truth Agent Skill
├── sec_research/
│   ├── __init__.py              # Metadata (v0.2.1)
│   ├── cli.py                   # Typer CLI application
│   ├── installer.py             # 1-command physical SKILL.md installer
│   ├── models.py                # Pydantic schemas & Data models
│   ├── storage.py               # SQLite FTS5 database & cache
│   ├── extractor.py             # PyMuPDF section segmenter
│   ├── mcp_server.py            # FastMCP server
│   └── providers/
│       ├── __init__.py          # Provider registry & parallel dispatcher
│       ├── base.py              # Base async provider interface
│       ├── arxiv.py             # arXiv cs.CR adapter
│       ├── usenix.py            # USENIX Security adapter
│       ├── ndss.py              # NDSS Symposium adapter
│       ├── iacr.py              # IACR ePrint adapter
│       └── nist.py              # NIST CSRC adapter
└── tests/
    ├── test_cli.py              # End-to-end CLI & installer tests
    ├── test_extractor.py        # PDF layout & section extraction tests
    ├── test_models.py           # Model serialization & tokens tests
    ├── test_providers.py        # Live and mocked repository tests
    └── test_storage.py          # SQLite FTS5 and cache tests

---

License

Distributed under the MIT License. All research papers accessed are hosted by their respective open-access academic institutions under Open Access and Public Domain licenses.