| Name | autopurple JSON |
| Version |
1.2.0
JSON |
| download |
| home_page | None |
| Summary | Claude-powered AWS security automation: discover vulnerabilities with ScoutSuite, validate with Pacu, and remediate via AWS MCP servers |
| upload_time | 2025-09-01 21:20:00 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT |
| keywords |
automation
aws
mcp
pacu
scoutsuite
security
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 🟣 AutoPurple
[](https://badge.fury.io/py/autopurple)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/autopurple/autopurple)
**Claude-powered AWS security automation: discover vulnerabilities with ScoutSuite, validate with Pacu, and remediate via AWS MCP servers**
AutoPurple is an intelligent AWS security automation system that combines the power of ScoutSuite discovery, Claude AI analysis, Pacu validation, and AWS MCP servers for end-to-end security remediation.
## 🎯 Mission
AutoPurple automates the complete AWS security assessment and remediation pipeline:
```
ScoutSuite Discovery → Claude Analysis → Pacu Validation → Claude Planning → MCP Remediation → Validation
```
## 🏗️ Architecture
### Core Principles
1. **Extension over replacement**: Reuse and extend ScoutSuite/Pacu; do not reimplement their core logic
2. **Remediation only after validation**: Never remediate unless Pacu confirms exploitability with evidence
3. **MCP-only infra changes**: All AWS changes are executed through AWS MCP servers
4. **Security-first**: Respect existing security mechanisms; least-privilege IAM; audit everything
5. **Async Python 3.11+**: Prefer `asyncio`/`anyio`, structured concurrency, timeouts, and robust error handling
### Components
- **ScoutSuite Adapter**: AWS security discovery and findings normalization
- **Pacu Adapter**: Exploit validation using Pacu's SQLite session
- **MCP Clients**: AWS CCAPI, CloudFormation, and Documentation MCP servers
- **Claude Planner**: AI-driven analysis and remediation planning
- **Pipeline Orchestrator**: Async DAG for the complete workflow
- **Post-Remediation Validator**: Confirmation of successful fixes
## 🚀 Quick Start
### Prerequisites
- Python 3.11+
- AWS credentials configured
- ScoutSuite installed
- Pacu installed
- MCP servers running (optional)
### Installation
```bash
# Clone the repository
git clone https://github.com/autopurple/autopurple.git
cd autopurple
# Install dependencies
pip install -e .
# Install development dependencies
pip install -e ".[dev]"
```
### Configuration
Create a `.env` file:
```bash
# Environment
AUTOPURPLE_ENV=dev
# AWS Configuration
AWS_PROFILE=default
AWS_REGION=us-east-1
# MCP Server Endpoints (optional)
MCP_ENDPOINT_CCAPI=http://localhost:8080
MCP_ENDPOINT_CFN=http://localhost:8081
MCP_ENDPOINT_DOCS=http://localhost:8082
# AI Configuration (optional)
CLAUDE_API_KEY=your_claude_api_key
# Database
AUTOPURPLE_DB_PATH=~/.autopurple/db.sqlite
```
### Usage
```bash
# Run the complete pipeline
autopurple run --profile my-aws-profile --region us-west-2 --max-findings 20
# Run in dry-run mode (default)
autopurple run --dry-run
# Run discovery only
autopurple discover --output findings.json
# Run validation only
autopurple validate findings.json
# Check system health
autopurple health
# Show recent runs
autopurple status
```
## 📊 Database Schema
AutoPurple uses SQLite with the following schema (compatible with Pacu):
```sql
-- AutoPurple runs table
CREATE TABLE ap_runs (
id TEXT PRIMARY KEY,
started_at TIMESTAMP NOT NULL,
ended_at TIMESTAMP,
aws_account TEXT,
aws_region TEXT,
status TEXT CHECK(status IN ('started','validated','remediated','failed')) NOT NULL,
notes TEXT
);
-- AutoPurple findings table
CREATE TABLE ap_findings (
id TEXT PRIMARY KEY,
run_id TEXT NOT NULL REFERENCES ap_runs(id) ON DELETE CASCADE,
source TEXT CHECK(source IN ('scoutsuite')) NOT NULL,
service TEXT NOT NULL,
resource_id TEXT NOT NULL,
title TEXT NOT NULL,
severity TEXT CHECK(severity IN ('low','medium','high','critical')) NOT NULL,
evidence JSON NOT NULL,
status TEXT CHECK(status IN ('new','validated','dismissed','remediated')) NOT NULL DEFAULT 'new'
);
-- AutoPurple validations table
CREATE TABLE ap_validations (
id TEXT PRIMARY KEY,
finding_id TEXT NOT NULL REFERENCES ap_findings(id) ON DELETE CASCADE,
tool TEXT CHECK(tool IN ('pacu')) NOT NULL,
module TEXT NOT NULL,
executed_at TIMESTAMP NOT NULL,
result TEXT CHECK(result IN ('exploitable','not_exploitable','error')) NOT NULL,
evidence JSON NOT NULL
);
-- AutoPurple remediations table
CREATE TABLE ap_remediations (
id TEXT PRIMARY KEY,
finding_id TEXT NOT NULL REFERENCES ap_findings(id) ON DELETE CASCADE,
planned_change JSON NOT NULL,
mcp_server TEXT NOT NULL,
mcp_call JSON NOT NULL,
executed_at TIMESTAMP,
status TEXT CHECK(status IN ('planned','executed','rolled_back','failed')) NOT NULL,
audit_ref TEXT
);
```
## 🔧 Development
### Project Structure
```
autopurple/
├── __init__.py
├── config.py # Configuration management
├── logging.py # Structured logging
├── db/
│ ├── __init__.py
│ ├── connection.py # Database connection
│ └── schema.sql # Database schema
├── models/
│ ├── __init__.py
│ ├── findings.py # Finding data models
│ ├── remediation.py # Remediation data models
│ ├── runs.py # Run data models
│ └── validations.py # Validation data models
├── adapters/
│ ├── __init__.py
│ ├── scoutsuite_adapter.py # ScoutSuite integration
│ ├── pacu_adapter.py # Pacu integration
│ └── mcp/
│ ├── __init__.py
│ ├── ccapi_client.py # AWS CCAPI MCP client
│ ├── cfn_client.py # AWS CloudFormation MCP client
│ └── docs_client.py # AWS Documentation MCP client
├── orchestrator/
│ ├── __init__.py
│ ├── pipeline.py # Main pipeline orchestrator
│ ├── planner.py # Claude planning
│ └── validators.py # Post-remediation validation
├── cli/
│ ├── __init__.py
│ └── main.py # CLI interface
└── tests/
├── unit/
└── integration/
```
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=autopurple
# Run specific test file
pytest tests/unit/test_findings.py
# Run integration tests
pytest tests/integration/
```
### Code Quality
```bash
# Run linting
ruff check .
# Run type checking
mypy autopurple/
# Run formatting
black autopurple/
```
## 🔒 Security Considerations
### Credential Management
- Use AWS profiles and STS tokens
- MFA required for AWS operations (configurable)
- Credentials stored in memory only
- Support for role assumption and chaining
### Least Privilege
- Generate example IAM policies for MCP operations
- Validate all MCP plans against allowlist
- Audit trail for every automated action
### Safety Features
- Dry-run mode enabled by default
- Explicit confirmation required for actual changes
- Rollback capabilities for all remediations
- Comprehensive logging and audit trails
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run the test suite
6. Submit a pull request
### Development Guidelines
- Follow the existing code style
- Add type hints to all functions
- Write comprehensive docstrings
- Include tests for new functionality
- Update documentation as needed
## 📝 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [ScoutSuite](https://github.com/nccgroup/ScoutSuite) - AWS security auditing
- [Pacu](https://github.com/RhinoSecurityLabs/pacu) - AWS exploitation framework
- [AWS MCP Servers](https://awslabs.github.io/mcp/servers/) - Model Context Protocol
- [Claude](https://anthropic.com/claude) - AI assistant for analysis and planning
## 📞 Support
- Issues: [GitHub Issues](https://github.com/autopurple/autopurple/issues)
- Documentation: [Read the Docs](https://autopurple.readthedocs.io)
- Discussions: [GitHub Discussions](https://github.com/autopurple/autopurple/discussions)
Raw data
{
"_id": null,
"home_page": null,
"name": "autopurple",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "automation, aws, mcp, pacu, scoutsuite, security",
"author": null,
"author_email": "AutoPurple Team <team@autopurple.dev>",
"download_url": "https://files.pythonhosted.org/packages/52/df/d1cde3e6289d8d0f7521790d7fe339245b6fe70234193024994c79072d0c/autopurple-1.2.0.tar.gz",
"platform": null,
"description": "# \ud83d\udfe3 AutoPurple\n\n[](https://badge.fury.io/py/autopurple)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/autopurple/autopurple)\n\n**Claude-powered AWS security automation: discover vulnerabilities with ScoutSuite, validate with Pacu, and remediate via AWS MCP servers**\n\nAutoPurple is an intelligent AWS security automation system that combines the power of ScoutSuite discovery, Claude AI analysis, Pacu validation, and AWS MCP servers for end-to-end security remediation.\n\n## \ud83c\udfaf Mission\n\nAutoPurple automates the complete AWS security assessment and remediation pipeline:\n\n```\nScoutSuite Discovery \u2192 Claude Analysis \u2192 Pacu Validation \u2192 Claude Planning \u2192 MCP Remediation \u2192 Validation\n```\n\n## \ud83c\udfd7\ufe0f Architecture\n\n### Core Principles\n\n1. **Extension over replacement**: Reuse and extend ScoutSuite/Pacu; do not reimplement their core logic\n2. **Remediation only after validation**: Never remediate unless Pacu confirms exploitability with evidence\n3. **MCP-only infra changes**: All AWS changes are executed through AWS MCP servers\n4. **Security-first**: Respect existing security mechanisms; least-privilege IAM; audit everything\n5. **Async Python 3.11+**: Prefer `asyncio`/`anyio`, structured concurrency, timeouts, and robust error handling\n\n### Components\n\n- **ScoutSuite Adapter**: AWS security discovery and findings normalization\n- **Pacu Adapter**: Exploit validation using Pacu's SQLite session\n- **MCP Clients**: AWS CCAPI, CloudFormation, and Documentation MCP servers\n- **Claude Planner**: AI-driven analysis and remediation planning\n- **Pipeline Orchestrator**: Async DAG for the complete workflow\n- **Post-Remediation Validator**: Confirmation of successful fixes\n\n## \ud83d\ude80 Quick Start\n\n### Prerequisites\n\n- Python 3.11+\n- AWS credentials configured\n- ScoutSuite installed\n- Pacu installed\n- MCP servers running (optional)\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/autopurple/autopurple.git\ncd autopurple\n\n# Install dependencies\npip install -e .\n\n# Install development dependencies\npip install -e \".[dev]\"\n```\n\n### Configuration\n\nCreate a `.env` file:\n\n```bash\n# Environment\nAUTOPURPLE_ENV=dev\n\n# AWS Configuration\nAWS_PROFILE=default\nAWS_REGION=us-east-1\n\n# MCP Server Endpoints (optional)\nMCP_ENDPOINT_CCAPI=http://localhost:8080\nMCP_ENDPOINT_CFN=http://localhost:8081\nMCP_ENDPOINT_DOCS=http://localhost:8082\n\n# AI Configuration (optional)\nCLAUDE_API_KEY=your_claude_api_key\n\n# Database\nAUTOPURPLE_DB_PATH=~/.autopurple/db.sqlite\n```\n\n### Usage\n\n```bash\n# Run the complete pipeline\nautopurple run --profile my-aws-profile --region us-west-2 --max-findings 20\n\n# Run in dry-run mode (default)\nautopurple run --dry-run\n\n# Run discovery only\nautopurple discover --output findings.json\n\n# Run validation only\nautopurple validate findings.json\n\n# Check system health\nautopurple health\n\n# Show recent runs\nautopurple status\n```\n\n## \ud83d\udcca Database Schema\n\nAutoPurple uses SQLite with the following schema (compatible with Pacu):\n\n```sql\n-- AutoPurple runs table\nCREATE TABLE ap_runs (\n id TEXT PRIMARY KEY,\n started_at TIMESTAMP NOT NULL,\n ended_at TIMESTAMP,\n aws_account TEXT,\n aws_region TEXT,\n status TEXT CHECK(status IN ('started','validated','remediated','failed')) NOT NULL,\n notes TEXT\n);\n\n-- AutoPurple findings table\nCREATE TABLE ap_findings (\n id TEXT PRIMARY KEY,\n run_id TEXT NOT NULL REFERENCES ap_runs(id) ON DELETE CASCADE,\n source TEXT CHECK(source IN ('scoutsuite')) NOT NULL,\n service TEXT NOT NULL,\n resource_id TEXT NOT NULL,\n title TEXT NOT NULL,\n severity TEXT CHECK(severity IN ('low','medium','high','critical')) NOT NULL,\n evidence JSON NOT NULL,\n status TEXT CHECK(status IN ('new','validated','dismissed','remediated')) NOT NULL DEFAULT 'new'\n);\n\n-- AutoPurple validations table\nCREATE TABLE ap_validations (\n id TEXT PRIMARY KEY,\n finding_id TEXT NOT NULL REFERENCES ap_findings(id) ON DELETE CASCADE,\n tool TEXT CHECK(tool IN ('pacu')) NOT NULL,\n module TEXT NOT NULL,\n executed_at TIMESTAMP NOT NULL,\n result TEXT CHECK(result IN ('exploitable','not_exploitable','error')) NOT NULL,\n evidence JSON NOT NULL\n);\n\n-- AutoPurple remediations table\nCREATE TABLE ap_remediations (\n id TEXT PRIMARY KEY,\n finding_id TEXT NOT NULL REFERENCES ap_findings(id) ON DELETE CASCADE,\n planned_change JSON NOT NULL,\n mcp_server TEXT NOT NULL,\n mcp_call JSON NOT NULL,\n executed_at TIMESTAMP,\n status TEXT CHECK(status IN ('planned','executed','rolled_back','failed')) NOT NULL,\n audit_ref TEXT\n);\n```\n\n## \ud83d\udd27 Development\n\n### Project Structure\n\n```\nautopurple/\n\u251c\u2500\u2500 __init__.py\n\u251c\u2500\u2500 config.py # Configuration management\n\u251c\u2500\u2500 logging.py # Structured logging\n\u251c\u2500\u2500 db/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 connection.py # Database connection\n\u2502 \u2514\u2500\u2500 schema.sql # Database schema\n\u251c\u2500\u2500 models/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 findings.py # Finding data models\n\u2502 \u251c\u2500\u2500 remediation.py # Remediation data models\n\u2502 \u251c\u2500\u2500 runs.py # Run data models\n\u2502 \u2514\u2500\u2500 validations.py # Validation data models\n\u251c\u2500\u2500 adapters/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 scoutsuite_adapter.py # ScoutSuite integration\n\u2502 \u251c\u2500\u2500 pacu_adapter.py # Pacu integration\n\u2502 \u2514\u2500\u2500 mcp/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 ccapi_client.py # AWS CCAPI MCP client\n\u2502 \u251c\u2500\u2500 cfn_client.py # AWS CloudFormation MCP client\n\u2502 \u2514\u2500\u2500 docs_client.py # AWS Documentation MCP client\n\u251c\u2500\u2500 orchestrator/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 pipeline.py # Main pipeline orchestrator\n\u2502 \u251c\u2500\u2500 planner.py # Claude planning\n\u2502 \u2514\u2500\u2500 validators.py # Post-remediation validation\n\u251c\u2500\u2500 cli/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 main.py # CLI interface\n\u2514\u2500\u2500 tests/\n \u251c\u2500\u2500 unit/\n \u2514\u2500\u2500 integration/\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=autopurple\n\n# Run specific test file\npytest tests/unit/test_findings.py\n\n# Run integration tests\npytest tests/integration/\n```\n\n### Code Quality\n\n```bash\n# Run linting\nruff check .\n\n# Run type checking\nmypy autopurple/\n\n# Run formatting\nblack autopurple/\n```\n\n## \ud83d\udd12 Security Considerations\n\n### Credential Management\n\n- Use AWS profiles and STS tokens\n- MFA required for AWS operations (configurable)\n- Credentials stored in memory only\n- Support for role assumption and chaining\n\n### Least Privilege\n\n- Generate example IAM policies for MCP operations\n- Validate all MCP plans against allowlist\n- Audit trail for every automated action\n\n### Safety Features\n\n- Dry-run mode enabled by default\n- Explicit confirmation required for actual changes\n- Rollback capabilities for all remediations\n- Comprehensive logging and audit trails\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Run the test suite\n6. Submit a pull request\n\n### Development Guidelines\n\n- Follow the existing code style\n- Add type hints to all functions\n- Write comprehensive docstrings\n- Include tests for new functionality\n- Update documentation as needed\n\n## \ud83d\udcdd License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- [ScoutSuite](https://github.com/nccgroup/ScoutSuite) - AWS security auditing\n- [Pacu](https://github.com/RhinoSecurityLabs/pacu) - AWS exploitation framework\n- [AWS MCP Servers](https://awslabs.github.io/mcp/servers/) - Model Context Protocol\n- [Claude](https://anthropic.com/claude) - AI assistant for analysis and planning\n\n## \ud83d\udcde Support\n\n- Issues: [GitHub Issues](https://github.com/autopurple/autopurple/issues)\n- Documentation: [Read the Docs](https://autopurple.readthedocs.io)\n- Discussions: [GitHub Discussions](https://github.com/autopurple/autopurple/discussions)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Claude-powered AWS security automation: discover vulnerabilities with ScoutSuite, validate with Pacu, and remediate via AWS MCP servers",
"version": "1.2.0",
"project_urls": {
"Documentation": "https://autopurple.readthedocs.io",
"Homepage": "https://github.com/autopurple/autopurple",
"Issues": "https://github.com/autopurple/autopurple/issues",
"Repository": "https://github.com/autopurple/autopurple"
},
"split_keywords": [
"automation",
" aws",
" mcp",
" pacu",
" scoutsuite",
" security"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6295f29b4c9254c084d38f821bbc05368e322a61247e2fe22a7e354f6b185cdb",
"md5": "60ca69ffa41348e5868e21428196122b",
"sha256": "bde7d5fb3e5a119e3ff2ceb83cee577c170cd315ed1f6637ae3ec7dfc2ed48d8"
},
"downloads": -1,
"filename": "autopurple-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "60ca69ffa41348e5868e21428196122b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 54648,
"upload_time": "2025-09-01T21:19:58",
"upload_time_iso_8601": "2025-09-01T21:19:58.170905Z",
"url": "https://files.pythonhosted.org/packages/62/95/f29b4c9254c084d38f821bbc05368e322a61247e2fe22a7e354f6b185cdb/autopurple-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "52dfd1cde3e6289d8d0f7521790d7fe339245b6fe70234193024994c79072d0c",
"md5": "1822171f6aaee5edde7f91fa5b23b874",
"sha256": "4a4e5ba925c74d023a8c62cf3594f4497dda30c2ea452d08876a54cd271727a8"
},
"downloads": -1,
"filename": "autopurple-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "1822171f6aaee5edde7f91fa5b23b874",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 70207,
"upload_time": "2025-09-01T21:20:00",
"upload_time_iso_8601": "2025-09-01T21:20:00.576384Z",
"url": "https://files.pythonhosted.org/packages/52/df/d1cde3e6289d8d0f7521790d7fe339245b6fe70234193024994c79072d0c/autopurple-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 21:20:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "autopurple",
"github_project": "autopurple",
"github_not_found": true,
"lcname": "autopurple"
}
