Metadata-Version: 2.5
Name: sec-research
Version: 0.2.2
Summary: Token-optimized CLI & Agent Skill for 100% Open Access academic cybersecurity research (USENIX, NDSS, IACR, arXiv, NIST).
Author: CyberSec Research Team
License: MIT
License-File: LICENSE
Keywords: agent-skills,ai-agents,arxiv,cybersecurity,iacr,infosec,mcp,ndss,nist,research,usenix
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: fastmcp>=0.4.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: lxml>=5.1.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: pymupdf>=1.24.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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.

[![PyPI version](https://img.shields.io/pypi/v/sec-research.svg?color=blue)](https://pypi.org/project/sec-research/)
[![CI](https://github.com/Walxom/sec-research/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Walxom/sec-research/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-brightgreen.svg)](https://python.org)
[![Zero Paywalls](https://img.shields.io/badge/Access-100%25%20Open%20Access-orange.svg)](#overview)
[![Token-Optimized](https://img.shields.io/badge/AI%20Context-Token%20Optimized-purple.svg)](#architecture-tri-layer-design)

---

## 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:

<p align="center">
  <img src="https://raw.githubusercontent.com/Walxom/sec-research/main/docs/assets/architecture.svg" alt="SecResearch Tri-Layer Architecture" width="100%" />
</p>

### 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

**From PyPI (Official Release)**:
```bash
# Install globally with pip:
pip install sec-research

# Or install with uv:
uv tool install sec-research

# Or run instantly without installing:
uvx sec-research search "Rowhammer"
```

**From Source (Development)**:
```bash
git clone https://github.com/Walxom/sec-research.git
cd sec-research

# Install in editable mode:
pip install -e .

# Or run directly via uv without installing:
uvx --from . sec-research --help
```

**1-Command Agent Skill Setup**:
```bash
# Setup skill for Google Antigravity, Claude Code, or Cursor:
sec-research setup --agent antigravity

# Or run setup directly via uvx:
uvx sec-research setup --agent all
```

---

## CLI Usage Guide

### 1. Unified Multi-Source Search
Search all 5 repositories concurrently in <350ms:
```bash
sec-research search "Rowhammer DRAM exploit" --limit 5
```

Filter by specific sources:
```bash
sec-research search "post-quantum lattice signature" --source iacr,nist --limit 3
```

Format for AI Agents (`--format json` or `--format markdown`):
```bash
sec-research search "BGP route hijacking" --source ndss,arxiv --format markdown
```

### 2. Dedicated Venue Commands
```bash
# 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:
```bash
# 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:
```bash
# 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:

```bash
# 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:

```bash
# 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):

```bash
sec-research mcp
```

Add to your `claude_desktop_config.json`:
```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.
