NeuroCAT - AI-Powered Security Hardening Agent

Intelligent CIS Benchmark Analysis and Remediation using AI

🎯 Overview

NeuroCAT is an AI-powered security administrator agent that leverages Ollama models and CIS (Center for Internet Security) benchmarks to automatically generate audit scripts and scan remote Linux servers for compliance.

Key Features

• 🤖 AI-Driven Script Generation: Uses local Ollama LLMs to generate robust audit scripts from PDF benchmarks
• 🎯 Targeted Auditing: CIS controls drive what to check - no blind scanning
• 🔒 Secure Remote Access: SSH-based auditing with password or key authentication
• 📊 Beautiful Reports: Generate JSON and HTML compliance reports
• ⚡ Optimized Workflow: Ingest benchmarks, generate scripts, and scan at scale

🏗️ Architecture

For a detailed view of the system architecture, please see ARCHITECTURE.md.

📋 Prerequisites

• Python: 3.10 or higher
• LLM Provider: Ollama (local) or OpenRouter (cloud)
• SSH Access: Remote server with SSH enabled
• CIS Benchmarks: PDF documents from CIS Benchmarks

🚀 Quick Start

1. Installation

# Clone the repository
git clone https://github.com/neur0cat/neurocat.git
cd neurocat

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Linux/Mac
# or
venv\Scripts\activate     # On Windows

# Install NeuroCAT
pip install -e .

# For development with testing tools
pip install -e ".[dev]"

2. Setup LLM Provider

Option A: Ollama (Local)

ollama serve
ollama pull llama3.2

Option B: OpenRouter (Cloud)

export OPENROUTER_API_KEY="your-api-key"
# Edit config.yaml: llm.provider = "openrouter"

3. Configure NeuroCAT

# Copy example configuration
cp config/config.example.yaml config/config.yaml

# Edit configuration (optional - defaults work for most cases)
nano config/config.yaml

4. Verify Installation

neurocat check

📖 Usage

1. Ingest Benchmarks for RAG

First, ingest a CIS benchmark PDF to create the vector embeddings needed for script generation.

# Ingest CIS benchmark into vector database
neurocat ingest -b benchmarks/CIS_Ubuntu_Linux_22.04.pdf

2. Generate Audit Scripts

Use the LLM to generate audit scripts for a specific profile (e.g., L1, L2).

# Generate from vectorstore (after running 'neurocat ingest')
neurocat generate -p L1

# Generate directly from PDF (will ingest first)
neurocat generate -b benchmarks/CIS_Ubuntu_Linux_22.04.pdf

3. Scan Remote System

Execute the generated scripts against a remote target.

# Scan with SSH key
neurocat scan \
  -h 192.168.1.100 \
  -u admin \
  -k ~/.ssh/id_rsa

# Scan with custom scripts directory
neurocat scan \
  -h 192.168.1.100 \
  -u admin \
  -k ~/.ssh/id_rsa \
  -s ./scripts

4. Parse and View Benchmark Info

# View benchmark structure and controls
neurocat parse -b benchmarks/CIS_Ubuntu_Linux_22.04.pdf

🏗️ Workflow

1. Ingest → Parse CIS PDF and create vector embeddings
2. Generate → Create sanitized audit scripts using LLM
3. Scan → Execute scripts on remote system and generate report

📁 Project Structure

neurocat/
├── src/neurocat/
│   ├── __init__.py
│   ├── __main__.py          # Entry point
│   ├── cli.py               # CLI commands (scan, generate, ingest, parse)
│   ├── script_generator.py  # Script generation with LLM repair
│   ├── llm_provider.py      # LLM provider factory
│   ├── config.py            # Configuration management
│   ├── errors.py            # Exception hierarchy and error handling
│   ├── logging_config.py    # Logging setup
│   ├── ollama_client.py     # Ollama client
│   ├── openrouter_client.py # OpenRouter client
│   ├── vector_store.py      # ChromaDB vector store for RAG
│   ├── ssh_manager.py       # SSH connection and command execution
│   └── cis_parser.py        # CIS benchmark PDF parser
├── tests/
│   ├── conftest.py          # Pytest configuration
│   ├── test_*.py            # Unit tests
│   └── test_integration.py  # Integration tests
├── config/
│   ├── config.yaml          # Active configuration
│   └── config.example.yaml  # Example configuration
├── benchmarks/              # Place CIS PDFs here
├── scripts/                 # Generated audit scripts
├── reports/                 # Generated reports
├── data/
│   ├── vectorstore/         # ChromaDB embeddings
│   └── benchmarks/          # Cached benchmark data
├── .github/
│   └── workflows/
│       └── ci.yml           # CI/CD pipeline
├── pyproject.toml           # Project metadata and dependencies
├── README.md
└── .gitignore

⚙️ Configuration

NeuroCAT uses a hierarchical configuration system:

Priority Order: CLI flags → Environment variables → Config file → Defaults

Configuration File

# config/config.yaml
ollama:
  url: "http://localhost:11434"
  model: "llama3.2"
  timeout: 300

ssh:
  port: 22
  timeout: 30
  key_filename: ~/.ssh/id_rsa

Environment Variables

export NEUROCAT_OLLAMA_URL="http://localhost:11434"
export NEUROCAT_OLLAMA_MODEL="llama3.2"
export NEUROCAT_SSH_PORT=22

Data Privacy

• ✅ CIS benchmarks contain no sensitive data
• ✅ Audit outputs stored locally only
• ✅ No data sent to external services (Ollama runs locally)

🧪 Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=neurocat --cov-report=html

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

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

# Run linters
ruff check src/ tests/
black --check src/ tests/

# Run type checker
mypy src/

📚 Documentation

• CIS Benchmarks - Official benchmark downloads
• Ollama Documentation - Ollama setup and models
• ChromaDB Docs - Vector database documentation

🐛 Troubleshooting

Ollama Connection Error

# Check if Ollama is running
curl http://localhost:11434/api/tags

# Start Ollama
ollama serve

SSH Authentication Failed

# Test SSH connection manually
ssh -i ~/.ssh/id_rsa user@host

# Check SSH key permissions
chmod 600 ~/.ssh/id_rsa

Model Not Found

# List available models
ollama list

# Pull required model
ollama pull llama3.2

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Center for Internet Security for comprehensive security benchmarks
• Ollama for local LLM inference
• ChromaDB for vector embeddings storage

📧 Contact

• Create an issue on GitHub
• Email: kkzone@gmail.com

---