Multi-LLM binary decompilation service with production-ready API, Docker deployment, and comprehensive testing. Features direct provider specification, open access architecture, and operational excellence.
A production-ready binary decompilation service that translates compiled binaries into natural language explanations using multiple LLM providers. Features clean architecture with direct provider specification, comprehensive testing, and full Docker deployment.
This skill guides you through building and operating a complete binary analysis service with:
```
src/
├── api/ # FastAPI endpoints and routing
├── analysis/ # Binary decompilation engine
├── llm/ # LLM provider integrations
├── models/ # Pydantic data models
├── cache/ # Result caching layer
└── core/ # Shared utilities and config
tests/
├── unit/ # Unit tests
├── integration/ # Integration tests
└── performance/ # Performance tests
docker/ # Container configurations
docs/ # Operational documentation
scripts/ # Deployment and housekeeping
0xcc/ # AI Dev Tasks Framework documents
```
1. **Create Project Structure**
- Set up modular monolith architecture: `src/{api,analysis,llm,models,cache,core}/`
- Initialize Python project with pyproject.toml
- Configure development tools: black, isort, mypy, pytest
2. **Establish Documentation Framework**
- Create `000_PPRD|bin2nlp.md` in `0xcc/prds/` (Project PRD)
- Create `000_PADR|bin2nlp.md` in `0xcc/adrs/` (Architecture Decision Record)
- Update CLAUDE.md with project standards and technology decisions
3. **Set Up Development Environment**
- Configure Docker Compose with API, PostgreSQL, and worker services
- Create environment templates: `.env.example`, `.env.development`
- Set up pre-commit hooks for code quality
1. **Implement Radare2 Integration**
- Create `src/analysis/decompiler.py` with r2pipe wrapper
- Build function extraction: entry point detection, assembly code capture
- Add binary validation and size limits (100MB default)
2. **Develop Storage Layer**
- Implement PostgreSQL models for jobs, results, and binaries
- Create file caching system with TTL support
- Add cleanup routines for temporary files
3. **Test Decompilation Engine**
- Unit tests for function detection (target: 10 functions in test binary)
- Integration tests for file processing pipeline
- Performance tests for 453KB binary processing (target: <50ms)
1. **Implement Direct Provider Architecture**
- Create `src/llm/base.py` with LLMProvider base class
- Implement on-demand provider creation from API request parameters
- Support OpenAI, Anthropic, Gemini, and Ollama providers
2. **Configure Primary LLM Service**
```python
# Environment configuration
OPENAI_API_KEY=ollama-local-key
OPENAI_BASE_URL=http://ollama.mcslab.io:80/v1
OPENAI_MODEL=phi4:latest
LLM_DEFAULT_PROVIDER=openai
```
3. **Add Translation Logic**
- Integrate assembly code with LLM prompts
- Parse LLM responses into structured explanations
- Implement error handling for API failures
1. **Build Core Endpoints**
- `POST /api/v1/analyze` - Binary upload and analysis
- `GET /api/v1/jobs/{job_id}` - Job status and results
- `GET /api/v1/health` - System health checks
- `GET /docs` - Auto-generated OpenAPI documentation
2. **Implement Job Management**
- Async background processing for long-running analyses
- Job queue with status tracking (pending, processing, completed, failed)
- Result caching with configurable TTL (1-24 hours)
3. **Add Validation & Error Handling**
- Pydantic models for request/response validation
- Custom exception hierarchy for business logic errors
- Structured error responses with appropriate HTTP status codes
1. **Docker Containerization**
- Multi-stage Dockerfile for API service
- PostgreSQL container with persistent volumes
- Nginx reverse proxy for production deployment
- Resource limits: API (512MB), Workers (2GB), PostgreSQL (1GB)
2. **Deployment Automation**
```bash
# One-command deployment
./scripts/deploy.sh development # or production
# Health validation
./scripts/health_check.sh
```
3. **Monitoring & Observability**
- Structured logging with correlation IDs
- Performance metrics collection (response times, LLM latency)
- Web dashboard at `/dashboard/` for real-time monitoring
- Background alert system for automated health checks
1. **Phase A: Foundation Validation**
- Health endpoints: Component status, system capabilities
- API documentation: OpenAPI spec availability
- Response times: Target 6-12ms for standard endpoints
2. **Phase B: Core Functionality**
- Decompilation accuracy: 10 functions detection in test binary
- File processing: 453KB binary upload in <50ms
- Job management: Queue operations and status tracking
3. **Phase C: Advanced Features**
- LLM integration: Provider health checks and API latency
- Translation quality: Assembly code explanation accuracy
- Admin functions: Metrics and dashboard operations
4. **Phase D: Performance & Scale**
- Concurrent handling: 10 simultaneous requests
- Resource efficiency: <50% memory usage under load
- Scalability: Horizontal scaling validation
5. **Phase E: Resilience & Failure**
- Database outage recovery: Graceful degradation
- Container restart: Health restoration in <10 seconds
- LLM provider failures: Proper error handling
- Input validation: File size limits and format checks
6. **Phase F: Security & Compliance**
- Input sanitization: File type validation
- Credential protection: No API key exposure
- Container security: Non-root execution
- Error message safety: No internal path disclosure
1. **Operational Guides**
- `docs/deployment.md` - Production deployment procedures
- `docs/runbooks.md` - Common operational scenarios
- `docs/llm-providers.md` - Multi-provider setup guide
- `docs/troubleshooting.md` - Diagnostic procedures
2. **Developer Documentation**
- API reference with example requests/responses
- Architecture diagrams and data flow
- Testing guidelines and coverage requirements
- Contributing guide and code review standards
```python
def create_provider(provider_name: str, api_key: str) -> LLMProvider:
"""Create LLM provider dynamically based on request parameters"""
if provider_name == "openai":
return OpenAIProvider(api_key=api_key, base_url=settings.openai_base_url)
elif provider_name == "anthropic":
return AnthropicProvider(api_key=api_key)
# ... other providers
```
```python
@router.post("/analyze")
async def analyze_binary(
file: UploadFile,
background_tasks: BackgroundTasks,
provider: str = "openai"
):
job_id = create_job()
background_tasks.add_task(process_binary, job_id, file, provider)
return {"job_id": job_id, "status": "pending"}
```
```python
@router.get("/health")
async def health_check():
return {
"status": "healthy",
"components": {
"api": "operational",
"database": await check_database(),
"llm_providers": "on-demand"
}
}
```
```bash
git commit -m "feat: [brief description]" -m "
```
```bash
./scripts/clear_resume
./scripts/hk --summary "Completed phase X" --next-steps "Begin phase Y"
@.housekeeping/QUICK_RESUME.md
```
```bash
/compact
@CLAUDE.md
@0xcc/spec/050_Developer_Coding_S&Ps.md
@0xcc/prds/000_PPRD|bin2nlp.md
@0xcc/adrs/000_PADR|bin2nlp.md
```
```bash
cp .env.example .env
OPENAI_API_KEY=your-key-here
OPENAI_BASE_URL=http://ollama.mcslab.io:80/v1
OPENAI_MODEL=phi4:latest
API_MEMORY_LIMIT=512m
WORKER_MEMORY_LIMIT=2g
POSTGRES_MEMORY_LIMIT=1g
```
```bash
./scripts/deploy.sh production
./scripts/health_check.sh
docker-compose logs -f api
```
```bash
pytest
pytest --cov=src --cov-report=html
pytest tests/integration/test_phase_*.py
```
1. **No Persistent Binary Storage**: Binaries are processed and discarded
2. **File Size Limits**: 100MB default maximum (configurable)
3. **Sandboxed Execution**: radare2 runs in isolated containers
4. **Open Access**: No user authentication required
5. **Stateless Operations**: Enables horizontal scaling
6. **Fail-Fast Validation**: Clear error messages for invalid inputs
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/bin2nlp-binary-analysis-with-direct-llm-integration/raw