# Copilot Instructions for Gato-X

Gato-X is a GitHub Actions enumeration and attack framework designed for security practitioners. When contributing to this project, follow these guidelines to maintain code quality, consistency, and security standards.

## Code Quality Standards

### Code Formatting
- **REQUIRED**: Format all Python code using Black before committing
- Run: `black gatox/` or `black .` to format the entire codebase
- Black configuration is defined in `pyproject.toml`
- All code must pass Black formatting checks

### Linting
- **REQUIRED**: Run Ruff on all code changes and fix issues before committing
- Run: `ruff check` to lint the codebase
- Run: `ruff check --fix` to auto-fix issues where possible
- Ruff configuration is defined in `pyproject.toml`
- Address all Ruff warnings and errors

### Import Sorting
- Use isort for consistent import ordering: `isort gatox/`
- Follow PEP8 import guidelines
- Group imports: standard library, third-party, local imports

### Code Style
- Follow PEP8 conventions
- Add docstrings to all public classes, methods, and functions
- Use type hints where appropriate
- Write clear, descriptive variable and function names

## Testing Requirements

### Running Tests
- Test suite is located in `unit_test/` directory
- Run tests with: `pytest`
- Ensure all tests pass before committing changes
- Test configuration is in `pyproject.toml`

### Writing Tests
- Add unit tests for all new functionality
- Use pytest framework with existing patterns
- Mock external dependencies (GitHub API calls, file operations)
- Test both success and failure scenarios
- Maintain or improve code coverage (currently configured to fail under 70%)

### Test Structure
- Place unit tests in `unit_test/` directory
- Mirror the source structure in test files
- Use descriptive test method names that explain what is being tested
- Group related tests in test classes where appropriate

## Documentation Standards

### API Changes and New Features
- **REQUIRED**: Update documentation for any API changes or new features
- Update relevant files in `docs/` directory
- Update CLI help text in the code when adding new commands or options
- Update README.md if the change affects installation or basic usage

### Documentation Structure
- User-facing documentation goes in `docs/user-guide/`
- Contribution guidelines go in `docs/contribution-guide/`
- Keep documentation current with code changes
- Use clear, practical examples in documentation

### Detection-Specific Requirements
- **REQUIRED**: Any new detection capabilities MUST include corresponding Fix/Mitigation instructions
- Add mitigation guidance to relevant documentation files
- Include defensive recommendations for each new attack technique
- Provide clear steps for remediation in documentation

## Security and Attack Features

### Attack Feature Guidelines
- Attack functionality must be isolated from enumeration features
- Any mutating operations should be clearly marked and documented
- Avoid mass exploit scenarios - target single resources only
- Include clear documentation of steps taken for penetration testing

### Defensive Documentation
- Include "Defensive Recommendations" sections for new attack techniques
- Provide monitoring and detection guidance
- Include related techniques and cross-references
- Follow the pattern established in existing use-case documentation

## MCP Server Integration

### Enum Feature Requirements
- **REQUIRED**: When adding new enumeration features, add corresponding tools to the MCP server
- MCP server code is located in `gatox/mcp/`
- Update MCP server capabilities in `gatox/mcp/mcp_server.py`
- Add new MCP tools following existing patterns
- Update MCP documentation in `docs/user-guide/mcp-server/mcp.md`

### MCP Tool Implementation
- Follow the fastmcp framework patterns
- Provide clear tool descriptions and parameter documentation
- Handle errors gracefully and provide meaningful error messages
- Test MCP tools with the MCP protocol

## Git and Version Control

### Commit Standards
- Write clear, descriptive commit messages
- Use conventional commit format when appropriate
- Keep commits focused and atomic
- Reference issues in commit messages when applicable

### Branch Strategy
- Create feature branches from `main`
- Use descriptive branch names (e.g., `feature/new-detection`, `fix/api-issue`)
- Ensure your branch is up to date with `main` before submitting

### Pull Request Requirements
- Ensure all code quality checks pass (Black, Ruff, tests)
- Update documentation as needed
- Include tests for new functionality
- Reference related issues
- Respond to code review feedback promptly

## Development Workflow

### Before Making Changes
1. Check existing issues and documentation
2. Understand the project's design methodology (operator-focused, avoid false negatives)
3. Consider performance implications for large-scale scanning

### Making Changes
1. Run linting and formatting tools frequently
2. Write tests as you develop features
3. Update documentation alongside code changes
4. Test changes thoroughly in different scenarios

### Before Committing
1. Run the complete test suite: `pytest`
2. Format code: `black .`
3. Lint code: `ruff check --fix`
4. Sort imports: `isort gatox/`
5. Verify documentation is updated
6. Check that new detections include mitigation docs
7. Ensure MCP server is updated for enum features

## Repository-Specific Considerations

### Performance Focus
- Gato-X is designed to scan thousands of repositories efficiently
- Consider API rate limiting in implementations
- Use caching appropriately (following existing patterns)
- Optimize for batch operations where possible

### Security Practitioner Focus
- Prioritize usability and effectiveness over perfect precision
- Provide sufficient context for operators to assess findings
- Tune for comprehensive coverage (prefer false positives over false negatives)
- Include clear remediation guidance

### GitHub Actions Expertise
- Understand GitHub Actions security model and common vulnerabilities
- Be familiar with workflow parsing, graph analysis, and attack vectors
- Consider both public and private repository scenarios
- Account for self-hosted runner security implications

## Getting Help

- Review existing documentation in `docs/`
- Check `CONTRIBUTING.md` for additional guidelines
- Look at existing code patterns for examples
- Open an issue for questions about significant changes

Remember: Gato-X is a security tool used by practitioners to identify real vulnerabilities. Code quality, accuracy, and clear documentation directly impact the effectiveness of security assessments.