CONTRIBUTING.md

Contributing to GoPlus AgentGuard

Thanks for your interest in contributing to GoPlus AgentGuard! Here's how to get started.

Development Setup

git clone https://github.com/GoPlusSecurity/agentguard.git
cd agentguard
npm install
npm run build
npm test

Project Structure

• src/ — TypeScript source code
  • scanner/ — Static analysis engine (20 detection rules)
  • action/ — Runtime action evaluator (exec, network, file, web3 detectors)
  • registry/ — Trust level management
  • policy/ — Default policies and capability presets
  • tests/ — Test suite (Node.js built-in test runner)
• skills/agentguard/ — Claude Code skill definition (SKILL.md + reference docs)
• hooks/ — Plugin hooks configuration for auto-guard
• examples/ — Demo projects for testing

Making Changes

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-change
3. Make your changes
4. Run npm run build && npm test to verify
5. Submit a pull request

Adding Detection Rules

New scan rules go in src/scanner/rules/. Each rule needs:

• A unique id (e.g., MY_NEW_RULE)
• severity: low | medium | high | critical
• pattern: regex to match against file content
• fileTypes: array of extensions to scan (e.g., ['.js', '.ts'])

Export the rule from the appropriate category file and add it to the ALL_RULES array in src/scanner/rules/index.ts.

Adding Action Detectors

Action detectors go in src/action/detectors/. They evaluate runtime actions and return risk assessments with tags.

Code Style

• TypeScript strict mode
• Zod for runtime validation
• Minimal dependencies (currently 5 production deps)
• Node.js built-in test runner (no test framework needed)

Reporting Issues

Please open an issue at https://github.com/GoPlusSecurity/agentguard/issues with:

• What you expected to happen
• What actually happened
• Steps to reproduce
• Your Node.js version and OS