Contributing

Getting Started

Provara is open source under the MIT license. Contributions are welcome.

Development Setup

# Clone the repository
git clone https://github.com/hunt-info-systems/provara.git
cd provara

# Install with dev dependencies
uv venv
uv sync --extra dev

# Verify setup
uv run pytest tests/ -v

Development Dependencies

Tool	Purpose
`pytest`	Test runner
`pytest-asyncio`	Async test support
`pytest-cov`	Coverage reporting
`mypy`	Static type checking
`ruff`	Linting and formatting

Code Standards

Style

Line length: 120 characters max
Python version: 3.12+ (use modern syntax)
Type hints: Required for all public functions
Docstrings: Required for all public functions and classes

Linting

# Check linting
uv run ruff check src/

# Auto-fix issues
uv run ruff check src/ --fix

# Type checking
uv run mypy src/

Testing

# Run all tests
uv run pytest tests/ -v

# With coverage
uv run pytest tests/ --cov=src --cov-report=term-missing

Tests use pytest with asyncio_mode = "auto" for async test support.

Project Structure

provara/
├── src/
│   ├── server/          # API server (core)
│   │   ├── main.py      # FastAPI endpoints
│   │   ├── config.py    # Configuration
│   │   └── exec/        # Execution engine
│   │       ├── policy.py    # Security policy
│   │       └── runner.py    # Command runner
│   ├── cli/             # CLI tools
│   └── ui/              # GUI application
├── agents/              # Agent integrations
├── scripts/             # PowerShell utilities
├── tests/               # Test suite
├── docs/                # Documentation source
└── pyproject.toml       # Project configuration

Contribution Areas

High Impact

Cross-platform support — Linux/macOS command execution backends
WebSocket approval UI — Real-time web-based approval interface
RBAC — Role-based access control for multi-user deployments
Command templates — Pre-approved command patterns

Medium Impact

Prometheus metrics — /metrics endpoint for monitoring
Command history search — Full-text search across execution records
Dry-run mode — Test commands against policy without execution
Batch approval — Approve multiple commands at once

Low Impact

OpenAPI customization — Enhanced API documentation
Docker support — Containerized deployment
CI/CD pipeline — GitHub Actions for testing and release

Pull Request Process

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Write tests for your changes

Ensure all checks pass:

uv run ruff check src/
uv run mypy src/
uv run pytest tests/ -v

Submit a pull request with a clear description

Security Contributions

If you discover a security vulnerability:

Do not open a public issue
Email details to the maintainers
Include steps to reproduce
Allow time for a fix before disclosure

License

By contributing, you agree that your contributions will be licensed under the MIT License.