---
description:
globs:
alwaysApply: true
---
# Strix Cybersecurity Agent - Project Rules

## Project Overview

### Goal and Purpose
Strix is a sophisticated cybersecurity agent specialized in vulnerability scanning and security assessment. It provides:
- Automated cybersecurity scans and assessments
- Web application security testing
- Infrastructure vulnerability analysis
- Comprehensive security reporting
- RESTful API for scan management
- CLI interface for direct usage

The project implements an AI-powered ReAct (Reasoning and Acting) framework for autonomous security testing.

## Project Structure

### High-Level Architecture
```
strix-agent/
├── strix/                  # Core application package
│   ├── agents/            # AI agent implementations
│   ├── api/               # FastAPI web service
│   ├── cli/               # Command-line interface
│   ├── llm/               # Language model configurations
│   └── tools/             # Security testing tools
├── tests/                 # Test suite
├── evaluation/            # Evaluation framework
├── containers/            # Docker configuration
└── docs/                  # Documentation
```

### Low-Level Structure

#### Core Components
- **[strix/agents/StrixAgent/strix_agent.py](mdc:strix/agents/StrixAgent/strix_agent.py)** - Main cybersecurity agent
- **[strix/agents/base_agent.py](mdc:strix/agents/base_agent.py)** - Base agent framework
- **[strix/api/main.py](mdc:strix/api/main.py)** - FastAPI application entry point
- **[strix/cli/main.py](mdc:strix/cli/main.py)** - CLI entry point
- **[pyproject.toml](mdc:pyproject.toml)** - Project configuration and dependencies

#### API Structure
- **[strix/api/routers/](mdc:strix/api/routers)** - API endpoint definitions
- **[strix/api/models/](mdc:strix/api/models)** - Pydantic data models
- **[strix/api/services/](mdc:strix/api/services)** - Business logic services

#### Security Tools
- **[strix/tools/browser/](mdc:strix/tools/browser)** - Web browser automation
- **[strix/tools/terminal/](mdc:strix/tools/terminal)** - Terminal command execution
- **[strix/tools/python/](mdc:strix/tools/python)** - Python code execution
- **[strix/tools/web_search/](mdc:strix/tools/web_search)** - Web reconnaissance
- **[strix/tools/reporting/](mdc:strix/tools/reporting)** - Security report generation

## Development Guidelines

### Code Standards
- **Simplicity**: Write simple, clean, and modular code
- **Functionality**: Prefer functional programming patterns where appropriate
- **Efficiency**: Optimize for performance without premature optimization
- **No Bloat**: Avoid unnecessary complexity or over-engineering
- **Minimal Comments**: Code should be self-documenting; use comments sparingly for complex business logic only

### Code Quality Requirements
- All code MUST pass `make pre-commit` checks
- All code MUST pass Ruff linting without warnings
- All code MUST pass MyPy type checking without errors
- Type hints are required for all function signatures
- Follow the strict configuration in [pyproject.toml](mdc:pyproject.toml)

### Execution Environment
- **ALWAYS** use `poetry run` for executing Python scripts and commands
- **NEVER** run Python directly with `python` command
- Use `poetry run strix-agent` for CLI operations
- Use `poetry run uvicorn strix.api.main:app` for API server

### File Management Rules
- **DO NOT** create or edit README.md or any .md documentation files unless explicitly requested
- Focus on code implementation, not documentation
- Keep docstrings concise and functional

### Testing and Quality Assurance
- Run `make pre-commit` before any commits
- Ensure all tests pass with `poetry run pytest`
- Use `poetry run mypy .` for type checking
- Use `poetry run ruff check .` for linting

### Dependencies
- All dependencies managed through [pyproject.toml](mdc:pyproject.toml)
- Use Poetry for dependency management
- Pin versions for production dependencies
- Keep dev dependencies in separate group

### Configuration
- Application settings in [strix/api/core/config.py](mdc:strix/api/core/config.py)
- LLM configuration in [strix/llm/config.py](mdc:strix/llm/config.py)
- Agent system prompts in [strix/agents/StrixAgent/system_prompt.jinja](mdc:strix/agents/StrixAgent/system_prompt.jinja)

## Key Implementation Patterns

### Agent Framework
- Inherit from BaseAgent for new agent implementations
- Use ReAct pattern for reasoning and action loops
- Implement tools through the registry system in [strix/tools/registry.py](mdc:strix/tools/registry.py)

### API Development
- Use FastAPI with Pydantic models
- Implement proper error handling and validation
- Follow REST conventions for endpoints
- Use Beanie ODM for MongoDB operations

### Security Tools
- Implement tools as action classes with clear interfaces
- Use async/await for I/O operations
- Implement proper cleanup and resource management
- Follow principle of least privilege

### Error Handling
- Use structured exception handling
- Provide meaningful error messages
- Log errors appropriately without exposing sensitive information
- Implement graceful degradation where possible