Instruction file imported from saltless-bruh/ai-auto-attack-framework (.github/instructions/framework_overview.instructions.md). Copyright stays with the author.

AI-Orchestrated Autonomous Attack Framework - Development Instructions

About This Instruction System

This project uses GitHub Copilot Instruction Files to provide persistent development guidance. These instruction files ensure consistent development practices, architectural adherence, and security-first implementation across all framework components.

Instruction Files Overview

Active Instruction Files

1. framework_requirements.instructions.md

   • Contains complete requirements specification
   • Defines acceptance criteria using EARS format
   • Applies to all files (applyTo: '**')
   • Source: .claude/specs/Requirements.md

2. framework_architecture.instructions.md

   • Defines architectural design principles
   • Documents component structure and interfaces
   • Provides coding standards and patterns
   • Applies to source code (applyTo: 'src/**')
   • Source: .claude/specs/Design.md

3. implementation_roadmap.instructions.md

   • Tracks implementation progress (Tasks 1-18)
   • Defines development priorities and phases
   • Provides task dependencies and estimates
   • Applies to all files (applyTo: '**')
   • Source: .claude/specs/Tasks.md

4. snyk_rules.instructions.md

   • Security scanning requirements (always active)
   • Runs Snyk scans on new code generation
   • Enforces security-at-inception practices
   • Source: .github/instructions/snyk_rules.instructions.md

Instruction File Hierarchy

Global Instructions (always active)
└── Project Instructions (.github/instructions/)
    ├── snyk_rules.instructions.md (security)
    ├── framework_overview.instructions.md (this file)
    ├── framework_requirements.instructions.md
    ├── framework_architecture.instructions.md
    └── implementation_roadmap.instructions.md

The .claude Folder

The .claude folder contains spec-driven development workflow configuration:

Purpose

This folder is used by Claude Code (or AI assistants in agent mode) to guide development of this framework - it's NOT part of the framework's runtime functionality.

Structure

.claude/
├── agents/kfc/              # Specialized agent specifications
│   ├── spec-design.md       # How to create design docs
│   ├── spec-impl.md         # How to implement features
│   ├── spec-judge.md        # How to evaluate work
│   ├── spec-requirements.md # How to gather requirements
│   ├── spec-test.md         # How to write tests
│   └── spec-tasks.md        # How to break down tasks
├── settings/
│   └── kfc-settings.json    # Workflow configuration
├── specs/                   # Project specifications
│   ├── Requirements.md      # ✅ Converted to instruction file
│   ├── Design.md            # ✅ Converted to instruction file
│   └── Tasks.md             # ✅ Converted to instruction file
└── system-prompts/
    └── spec-workflow-starter.md  # Workflow orchestration

Relationship to Instruction Files

The specifications in .claude/specs/ have been converted to GitHub Copilot instruction files in .github/instructions/ to work with the Instruction Files feature. The content is preserved but formatted for automatic loading by Copilot.

Key Distinction:

• .claude/ folder: Workflow configuration for AI-assisted development (meta-level)
• src/ folder: The actual framework that uses AI agents for penetration testing (runtime)
• .github/instructions/: GitHub Copilot instructions derived from .claude/specs/

Framework Overview

What This Framework Does

An AI-orchestrated autonomous attack framework that:

1. Uses hybrid AI strategy with clear role separation:
   • Claude API for MCP tool orchestration only (20% usage)
   • Gemini API for development/testing (free tier, 10% usage)
   • DeepSeek-R1:8b (local) for all local tasks: attack planning, reasoning, parsing, and report generation (70% usage)
2. Integrates security tools via Model Context Protocol (MCP)
3. Decomposes penetration testing into discrete AI-executed tasks
4. Maintains state across multi-stage attack workflows
5. Enforces authorization controls and audit logging
6. Achieves 70% cost savings through single local 14B model deployment

Core Architecture Layers

┌─────────────────────────────────────────┐
│     Orchestration Layer                 │
│  (AI Model + Task Management)           │
├─────────────────────────────────────────┤
│     MCP Integration Layer               │
│  (Client, Router, Configuration)        │
├─────────────────────────────────────────┤
│     Security Tools Layer                │
│  (MCP Servers: Recon, Vuln, Exploit)    │
├─────────────────────────────────────────┤
│     Data Layer                          │
│  (State Management, Audit Logs)         │
└─────────────────────────────────────────┘

Project Directory Structure

ai_auto_attack_framework/
├── .claude/                    # AI development workflow specs
├── .github/
│   └── instructions/           # ⭐ GitHub Copilot instruction files
├── src/                        # Framework source code
│   ├── orchestration/          # AI orchestration engine
│   ├── mcp/                    # MCP client and router
│   ├── tools/                  # MCP server implementations
│   ├── state/                  # State management
│   ├── evaluation/             # Agent evaluation
│   └── utils/                  # Shared utilities
├── tests/                      # Comprehensive test suite
├── config/                     # Configuration files
│   ├── framework-config.yaml
│   └── authorization-scope.yaml
├── docs/                       # Documentation
└── examples/                   # Example engagements

Development Workflow

Starting New Work

1. Review current status in implementation_roadmap.instructions.md
2. Check requirements for the feature you're implementing
3. Follow architecture patterns from framework_architecture.instructions.md
4. Write tests first (TDD approach)
5. Run security scans (Snyk) before committing
6. Update documentation as you implement

When You're Working On...

Orchestration Components (src/orchestration/)

• Follow patterns in OrchestrationEngine, TaskManager, WorkflowEngine
• Integrate with AuthorizationManager for all security actions
• Log all activities via AuditLogger
• Maintain state via StateManager

MCP Servers (src/tools/)

• Extend BaseMCPServer class
• Implement JSON-RPC 2.0 protocol
• Add parameter validation with JSON Schema
• Write integration tests with vulnerable targets
• Document all tools in server's list_tools() method

State Management (src/state/)

• Use encryption for sensitive data (credentials, API keys)
• Maintain ACID properties for critical operations
• Support engagement resume/recovery
• Implement efficient querying with filtering

Testing (tests/)

• Unit tests: Mock external dependencies (AI models, MCP servers)
• Integration tests: Use Docker containers for realistic environments
• Security tests: Validate authorization controls at all boundaries
• Achieve 80%+ code coverage

Security-First Development

ALWAYS:

• Check authorization before executing any security tool
• Log all actions with full context
• Encrypt sensitive data at rest
• Never log API keys or credentials in plaintext
• Run Snyk scans on new code
• Validate user inputs
• Use secure defaults in configuration

NEVER:

• Bypass authorization checks
• Execute tools outside authorized scope
• Store credentials unencrypted
• Allow arbitrary code execution without sandboxing
• Trust user input without validation

Current Implementation Status

✅ Completed (Tasks 1-5)

• Project structure and development environment
• Core data models and database layer (100% coverage)
• MCP client and router infrastructure (85% coverage)
• All MCP servers implemented (Recon, Vuln, Exploit, Cred, Web, Data, CMD)
• Authorization and audit infrastructure (100% coverage)

✅ Completed (Tasks 6-7) - CRITICAL PATH

• Task 6: Task Manager and Workflow Engine (100% COMPLETE)
• Task 7: AI Orchestration Engine (100% COMPLETE)
• Task 10: CLI Interface (COMPLETE)

🚧 Partial Implementation (Tasks 8-9, 11)

• Error handling and resilience (75% complete)
• Reporting and documentation system (60% complete)
• Tool output processing (70% complete)

⏳ Upcoming (Tasks 12-18)

• Configuration and extensibility
• Comprehensive testing
• Deployment and packaging
• Security review and hardening
• Final validation

Key Principles to Remember

1. Separation of Concerns

• Orchestration logic separate from tool execution
• State management isolated from business logic
• Authorization enforcement at boundaries

2. Security by Default

• All actions require authorization
• Complete audit trail maintained
• Sensitive data encrypted
• Human approval for critical operations

3. Extensibility

• New MCP servers via configuration
• Custom workflows via YAML
• Plugin system for extensions
• No core code changes needed for additions

4. Resilience

• Retry logic with exponential backoff
• Graceful error handling
• Engagement resume capability
• Alternative tool suggestions

5. Transparency

• Complete audit logging
• Comprehensive reporting
• Attack path visualization
• Evidence collection

Using These Instructions

For Development

• These instructions are automatically loaded by GitHub Copilot
• No need to reference them explicitly in prompts
• They provide context for all code generation and modification
• Update them as the project evolves

For Code Review

• Validate changes against requirements in instruction files
• Check architectural adherence to design patterns
• Verify security controls are implemented
• Ensure tests are comprehensive

For Onboarding

• Read all instruction files to understand the framework
• Review .claude/specs/ for detailed specifications
• Examine src/ for implementation examples
• Run tests to validate setup

Compliance and Ethics

CRITICAL REMINDER: This framework is for authorized penetration testing ONLY.

Authorized Use Cases

✅ Written consent from target organization ✅ Controlled laboratory environments ✅ Educational purposes with safeguards ✅ Organizational red team exercises

Prohibited Use Cases

❌ Unauthorized access to systems ❌ Malicious activities ❌ Illegal purposes ❌ Production attacks

Misuse may result in criminal prosecution.

Getting Help

Questions About...

• Requirements: See framework_requirements.instructions.md
• Architecture: See framework_architecture.instructions.md
• Implementation: See implementation_roadmap.instructions.md
• Detailed specs: See .claude/specs/*.md
• Current code: See src/ directory
• Testing: See tests/ directory
• Security: See snyk_rules.instructions.md and authorization documentation

Contributing

1. Understand the instruction files
2. Follow the implementation roadmap
3. Maintain test coverage (80%+)
4. Run security scans (Snyk)
5. Update documentation
6. Submit for code review

Instruction File Maintenance

When to Update These Files

• ✅ Requirements change or new requirements added
• ✅ Architecture evolves or new patterns emerge
• ✅ Tasks completed or priorities shift
• ✅ Security guidelines updated
• ✅ New best practices identified

How to Update

1. Edit the instruction file in .github/instructions/
2. Ensure YAML frontmatter is correct (applyTo, description)
3. Maintain markdown formatting
4. Update cross-references if needed
5. Commit with descriptive message

Remember: These instructions guide AI-assisted development of the framework. The framework itself (in src/) is what performs AI-orchestrated penetration testing.