Inspectra Development Guide

Getting Started

Prerequisites

Rust toolchain (1.70+)

# Install rustup from https://rustup.rs
rustup install stable
rustup default stable

Python (3.8+) - for bindings
```
# Check Python version
python --version
```
Git
```
git --version
```

First Build

Clone the repository:

git clone https://github.com/nodasys/inspectra.git
cd inspectra

Build the core:
```
cargo build
```
Run tests:
```
cargo test
```
Run examples:
```
cargo run --example list_processes
```

Project Structure

inspectra/
├── core/                   # Core Rust library
│   ├── src/
│   │   ├── lib.rs         # Main library entry
│   │   ├── error.rs       # Error types
│   │   ├── types.rs       # Common types
│   │   ├── process/       # Process management
│   │   ├── memory/        # Memory operations
│   │   ├── scanner/       # Memory scanning
│   │   ├── pointer/       # Pointer analysis
│   │   ├── debugger/      # Debugging & patching
│   │   └── platform/      # Platform-specific code
│   └── examples/          # Usage examples
│
├── bindings/
│   └── python/            # Python bindings
│       ├── src/           # Rust FFI code
│       ├── inspectra/     # Python package
│       └── examples/      # Python examples
│
├── tests/                 # Integration tests
├── docs/                  # Documentation
├── scripts/               # Build scripts
└── .github/workflows/     # CI/CD

Development Workflow

1. Create a Feature Branch

git checkout -b feat/your-feature

2. Make Changes

Edit code in your IDE (VS Code recommended with rust-analyzer).

3. Format Code

cargo fmt

4. Run Linter

cargo clippy --all-targets --all-features -- -D warnings

5. Run Tests

cargo test --all

6. Build

# Debug build
cargo build

# Release build
cargo build --release

7. Test Examples

cargo run --example list_processes
cargo run --example memory_scanner
cargo run --example pattern_scan

Python Bindings Development

Setup

cd bindings/python
pip install maturin

Development Build

# Build and install in development mode
maturin develop

# Test
python examples/list_processes.py

Release Build

maturin build --release

Testing

Unit Tests

# Run all tests
cargo test

# Run specific test
cargo test test_process_listing

# Run with output
cargo test -- --nocapture

Integration Tests

cargo test --test integration_tests

Coverage

# Install tarpaulin
cargo install cargo-tarpaulin

# Generate coverage
cargo tarpaulin --verbose --all-features --workspace

Debugging

Rust

Use VS Code with rust-analyzer:

Set breakpoints in code
F5 to start debugging

Logs

Enable logging:

$env:RUST_LOG="debug"
cargo run --example list_processes

Common Tasks

Add a New Module

Create file in core/src/your_module.rs
Add pub mod your_module; to lib.rs
Export public items in lib.rs
Write tests
Update documentation

Update Dependencies

# Check for outdated dependencies
cargo outdated

# Update dependencies
cargo update

Security Audit

# Install cargo-audit
cargo install cargo-audit

# Run audit
cargo audit

Performance Profiling

Benchmarks

cargo bench

Profiling

Use tools like:

Windows: Visual Studio Profiler, Windows Performance Analyzer
Linux: perf, valgrind
Cross-platform: cargo-flamegraph

Documentation

Generate Docs

cargo doc --no-deps --open

Write Docs

Use Rust doc comments:

/// This function does something
///
/// # Examples
///
/// ```
/// use inspectra_core::example;
/// example();
/// ```
pub fn example() {
    // ...
}

CI/CD

GitHub Actions automatically:

Runs tests on Windows, Linux, macOS
Checks formatting
Runs Clippy
Generates coverage report

View results in the Actions tab on GitHub.

Tips

Use cargo check for fast compilation checks
Use cargo watch for continuous compilation
Enable all Clippy lints during development
Write tests first (TDD)
Document public APIs thoroughly
Handle errors properly - don't panic!

Troubleshooting

Windows API Errors

Make sure to run with administrator privileges:

# Run PowerShell as Administrator
Start-Process powershell -Verb runAs

Linux Permission Denied

Use ptrace permissions:

echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

Python Binding Issues

Reinstall in development mode:

cd bindings/python
pip uninstall inspectra
maturin develop --release

Uh oh!