Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
90 lines (69 loc) · 3.34 KB

CONTRIBUTING.md

File metadata and controls

90 lines (69 loc) · 3.34 KB
Raw

Contributing to localagent 🛡️

Thank you for your interest in contributing to localagent! We welcome bug fixes, security enhancements, performance improvements, and feature extensions.

localagent is built with a security-conscious, defense-in-depth design. All contributions must uphold our strict security guarantees.

🔒 Core Security Guidelines

When contributing code to localagent, you must adhere to the following principles:

  1. Pre-Execution Validation: Security checks (path jailing, AST command token validation, binary whitelisting) MUST execute and pass before any tool call is dispatched to MCP server sub-processes or filesystem APIs.
  2. Zero Partial Execution: Never touch, create, or modify files before security verification.
  3. Default Restrictive Stance: All new security features or sandbox modes must default to the most restrictive setting (e.g. network isolation disabled by default).
  4. Audit Hash Chain Integrity: Any modifications to internal/audit must preserve SHA-256 hash chaining (prev_hash & entry_hash) and pass VerifyChain() validation.

🛠️ Development Setup

Prerequisites

  • Go: Version 1.22 or higher
  • Ollama: Local instance running at http://localhost:11434 (ollama run llama3.2)
  • Bubblewrap (bwrap): Optional for testing strict sandbox mode on Linux (sudo apt install bubblewrap)

Building from Source

# Clone repository
git clone https://github.com/GunaTeja777/Local-first-LLM-Agent-with-MCP-Tool-Orchestration.git
cd Local-first-LLM-Agent-with-MCP-Tool-Orchestration

# Build binary
go build -o localagent ./cmd/localagent

📂 Repository Layout

.
├── cmd/
│   └── localagent/       # CLI entrypoint and flag parsing
├── demo/                 # Adversarial escape verification suite & report
├── internal/
│   ├── agent/            # Core ReAct loop & Ollama orchestration
│   ├── audit/            # SHA-256 hash-chained JSONL logger & verifier
│   ├── config/           # Configuration parsing & validation
│   ├── mcp/              # MCP JSON-RPC stdio transport & tool schema mapper
│   ├── provider/         # Ollama HTTP API provider client
│   └── sandbox/          # Path jailing & basic/strict sandbox engines
├── go.mod                # Go module definition
├── README.md             # Project overview & architecture
├── THREAT_MODEL.md       # Explicit threat model & non-goals
└── CONTRIBUTING.md       # Contribution guidelines

🧪 Testing & Verification Checklist

Before submitting a Pull Request, ensure your changes pass all unit tests and security checks:

  1. Run Unit Tests: 
    go test ./... -v
  2. Run Security Escape Verification Suite: 
    chmod +x demo/escape_attempts.sh
./demo/escape_attempts.sh
  3. Verify Audit Chain Integrity: 
    ./localagent -verify-audit audit.jsonl

📬 Submitting Pull Requests

  1. Create a Feature Branch: 
    git checkout -b feature/your-feature-name
  2. Commit Your Changes: Write clear, concise commit messages explaining why the change was made.
  3. Open a Pull Request: Describe your changes, reference any relevant issue numbers, and confirm that all test checks pass.