26 KiB
26 KiB
IaC Reverse Engineering Tool — User Walkthrough
Bring your unmanaged on-premises infrastructure under Terraform control in minutes.
What This Tool Does
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ Your Live Infrastructure Generated Terraform Output │
│ │
│ ┌──────────────┐ ┌──────────────────────┐ │
│ │ Kubernetes │──┐ │ kubernetes_deploy.tf │ │
│ │ Cluster │ │ │ kubernetes_svc.tf │ │
│ └──────────────┘ │ │ docker_service.tf │ │
│ ┌──────────────┐ │ iac-reverse │ windows_service.tf │ │
│ │ Docker Swarm │──┼──────────────▶│ synology_volume.tf │ │
│ │ Cluster │ │ generate │ harvester_vm.tf │ │
│ └──────────────┘ │ │ variables.tf │ │
│ ┌──────────────┐ │ │ providers.tf │ │
│ │ Windows │──┤ │ terraform.tfstate │ │
│ │ Servers │ │ └──────────────────────┘ │
│ └──────────────┘ │ │
│ ┌──────────────┐ │ │
│ │ Synology NAS │──┤ │
│ └──────────────┘ │ │
│ ┌──────────────┐ │ │
│ │ Harvester │──┘ │
│ │ HCI │ │
│ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Table of Contents
- Prerequisites
- Installation
- Quick Start
- Creating Scan Profiles
- Running a Scan
- Generating Terraform Code
- Incremental Scanning (Diff)
- Validating Output
- Authentik SSO Login
- Supported Providers
- Troubleshooting
Prerequisites
Before installing, make sure you have:
| Requirement | Version | Purpose |
|---|---|---|
| Python | 3.11+ | Runtime |
| pip | Latest | Package installation |
| Terraform | 1.5+ | Output validation (optional) |
| Git | Any | Cloning the repo |
Platform-specific requirements for scanning:
| Provider | Requirement |
|---|---|
| Kubernetes | Valid kubeconfig file |
| Docker Swarm | Docker daemon access (TCP or socket) |
| Windows | WinRM enabled on target machines |
| Synology | DSM admin credentials |
| Harvester | Harvester cluster kubeconfig |
| Bare Metal | BMC/iDRAC Redfish API access |
Installation
Step 1: Clone the repository
git clone https://github.com/your-org/SnarfCode.git
cd SnarfCode
Step 2: Install the tool
# Install in development mode (recommended)
pip install -e ".[dev]"
Step 3: Verify installation
iac-reverse --version
Expected output:
iac-reverse, version 0.1.0
┌─────────────────────────────────────────────────────────────┐
│ ✓ Installation Complete │
│ │
│ You now have access to: │
│ • iac-reverse scan Discover infrastructure │
│ • iac-reverse generate Full pipeline (scan → HCL) │
│ • iac-reverse diff Incremental change detection │
│ • iac-reverse validate Validate generated output │
│ • iac-reverse login Authentik SSO authentication │
│ │
└─────────────────────────────────────────────────────────────┘
Quick Start
The fastest way to get going — scan your Kubernetes cluster and generate Terraform:
# 1. Create a scan profile
cat > my-cluster.yaml << EOF
provider: kubernetes
credentials:
kubeconfig_path: ~/.kube/config
context: my-cluster
endpoints:
- https://k8s-api.internal.lab:6443
EOF
# 2. Generate Terraform code
iac-reverse generate --profile my-cluster.yaml --output-dir ./terraform-output
# 3. Check the results
ls terraform-output/
That's it! You now have Terraform HCL + state for your cluster.
Creating Scan Profiles
Scan profiles are YAML files that tell the tool what to scan and how to authenticate.
Profile Structure
provider: <provider_type> # Required: kubernetes, docker_swarm, synology, etc.
credentials: # Required: provider-specific auth
key: value
endpoints: # Optional: API endpoints to scan
- https://api.example.com:6443
resource_type_filters: # Optional: limit which resource types to discover
- kubernetes_deployment
- kubernetes_service
authentik_token: <token> # Optional: SSO token from Authentik
Environment Variable Expansion
Use ${ENV_VAR} syntax in credential fields to avoid hardcoding secrets:
provider: synology
credentials:
host: nas01.internal.lab
port: "5001"
username: "${SYNOLOGY_USER}"
password: "${SYNOLOGY_PASSWORD}"
use_ssl: "true"
You can also provide defaults with ${ENV_VAR:-default_value}:
credentials:
port: "${SYNOLOGY_PORT:-5001}"
Example Profiles
Kubernetes (Raspberry Pi Cluster)
provider: kubernetes
credentials:
kubeconfig_path: "${HOME}/.kube/config"
context: "pi-cluster"
endpoints:
- "https://k8s-api.internal.lab:6443"
resource_type_filters:
- kubernetes_deployment
- kubernetes_service
- kubernetes_ingress
- kubernetes_config_map
- kubernetes_persistent_volume
- kubernetes_namespace
Docker Swarm
provider: docker_swarm
credentials:
host: "tcp://swarm-manager.internal.lab:2376"
tls_verify: "true"
cert_path: "${HOME}/.docker/certs"
Windows Server
provider: windows
credentials:
host: "win-server-01.internal.lab"
username: "${WINDOWS_USER}"
password: "${WINDOWS_PASSWORD}"
transport: "ntlm"
port: "5986"
use_ssl: "true"
resource_type_filters:
- windows_service
- windows_scheduled_task
- windows_iis_site
- windows_iis_app_pool
- windows_feature
- windows_hyperv_vm
Synology NAS
provider: synology
credentials:
host: "nas01.internal.lab"
port: "5001"
username: "${SYNOLOGY_USER}"
password: "${SYNOLOGY_PASSWORD}"
use_ssl: "true"
resource_type_filters:
- synology_shared_folder
- synology_volume
- synology_storage_pool
SUSE Harvester (Dell PowerEdge)
provider: harvester
credentials:
kubeconfig_path: "${HOME}/.kube/harvester-config"
context: "harvester-cluster"
endpoints:
- "https://harvester.internal.lab:6443"
Bare Metal (IPMI/Redfish)
provider: bare_metal
credentials:
host: "bmc-server01.internal.lab"
username: "${BMC_USER}"
password: "${BMC_PASSWORD}"
port: "443"
use_ssl: "true"
Multi-Provider (scan everything at once)
- provider: kubernetes
credentials:
kubeconfig_path: ~/.kube/config
context: pi-cluster
endpoints:
- https://k8s-api.internal.lab:6443
- provider: synology
credentials:
host: nas01.internal.lab
port: "5001"
username: "${SYNOLOGY_USER}"
password: "${SYNOLOGY_PASSWORD}"
- provider: windows
credentials:
host: win-server-01.internal.lab
username: "${WINDOWS_USER}"
password: "${WINDOWS_PASSWORD}"
transport: ntlm
port: "5986"
use_ssl: "true"
Running a Scan
The scan command discovers resources without generating any output files. Useful for previewing what the tool will find.
iac-reverse scan --profile my-cluster.yaml
Example output:
Loading scan profile: my-cluster.yaml
Provider: kubernetes
Creating plugin...
Starting scan...
[1/6] Scanning kubernetes_deployment... (12 resources found)
[2/6] Scanning kubernetes_service... (18 resources found)
[3/6] Scanning kubernetes_ingress... (4 resources found)
[4/6] Scanning kubernetes_config_map... (23 resources found)
[5/6] Scanning kubernetes_persistent_volume... (6 resources found)
[6/6] Scanning kubernetes_namespace... (5 resources found)
Scan complete: 68 resources discovered
┌─────────────────────────────────────────────────────────────┐
│ │
│ Pipeline Flow: scan command │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Profile │───▶│ Scanner │───▶│ Resource Summary │ │
│ │ (YAML) │ │ │ │ (terminal) │ │
│ └──────────┘ └──────────┘ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Generating Terraform Code
The generate command runs the full pipeline: scan → resolve dependencies → generate HCL → build state → validate.
iac-reverse generate --profile my-cluster.yaml --output-dir ./terraform-output
Example output:
Loading scan profile: my-cluster.yaml
Step 1/5: Scanning infrastructure...
[1/6] Scanning kubernetes_deployment... (12 resources found)
[2/6] Scanning kubernetes_service... (18 resources found)
...
Found 68 resources
Step 2/5: Resolving dependencies...
Resolved 42 relationships, 0 cycles detected
Step 3/5: Generating Terraform code...
Generated 6 resource files
Step 4/5: Building Terraform state...
State file: 68 entries
Step 5/5: Validating output...
✓ Validation passed
Generation complete:
Output directory: ./terraform-output
Resource files: 6
Total resources: 68
Generated file structure:
terraform-output/
├── kubernetes_deployment.tf # All deployments
├── kubernetes_service.tf # All services
├── kubernetes_ingress.tf # All ingresses
├── kubernetes_config_map.tf # All config maps
├── kubernetes_persistent_volume.tf
├── kubernetes_namespace.tf
├── variables.tf # Extracted shared variables
├── providers.tf # Provider configuration
└── terraform.tfstate # State binding to live resources
┌─────────────────────────────────────────────────────────────────────┐
│ │
│ Pipeline Flow: generate command │
│ │
│ ┌────────┐ ┌─────────┐ ┌──────────┐ ┌───────┐ ┌───────────┐ │
│ │Profile │─▶│ Scanner │─▶│ Resolver │─▶│ Code │─▶│ State │ │
│ │ YAML │ │ │ │ │ │ Gen │ │ Builder │ │
│ └────────┘ └─────────┘ └──────────┘ └───────┘ └───────────┘ │
│ │ │
│ ▼ │
│ ┌───────────┐ │
│ │ Validator │ │
│ └───────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Incremental Scanning (Diff)
After your initial scan, use diff to detect infrastructure changes without regenerating everything.
iac-reverse diff --profile my-cluster.yaml
Example output:
Loading scan profile: my-cluster.yaml
Loading previous snapshot...
Previous snapshot: 2024-01-14T09:00:00Z (65 resources)
Scanning infrastructure...
[1/6] Scanning kubernetes_deployment... (14 resources found)
...
Comparing with previous scan...
Snapshot saved
Change Summary:
Added: 3
Removed: 1
Modified: 2
+ kubernetes_deployment/new-api-service
+ kubernetes_service/new-api-svc
+ kubernetes_ingress/new-api-ingress
- kubernetes_deployment/deprecated-worker
~ kubernetes_deployment/web-frontend (replicas: 3 → 5)
~ kubernetes_service/web-svc (port: 8080 → 9090)
┌─────────────────────────────────────────────────────────────┐
│ │
│ Incremental Scan Flow │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Previous │ │ Current │ │ │ │
│ │ Snapshot │───▶│ Scan │───▶│ Change Summary │ │
│ │ (JSON) │ │ │ │ + Added │ │
│ └──────────┘ └──────────┘ │ - Removed │ │
│ │ ~ Modified │ │
│ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Validating Output
Run standalone validation against existing Terraform output:
iac-reverse validate --dir ./terraform-output
Example output (success):
Validating: ./terraform-output
Validation Results:
terraform init: ✓
terraform validate: ✓
terraform plan: ✓
✓ All validations passed - no drift detected
Example output (drift detected):
Validating: ./terraform-output
Validation Results:
terraform init: ✓
terraform validate: ✓
terraform plan: ✗
Planned Changes (2):
modify: kubernetes_deployment.web_frontend
add: kubernetes_service.new_backend
⚠ Validation passed but drift detected
Authentik SSO Login
If your infrastructure uses Authentik for identity management, authenticate first:
iac-reverse login \
--url https://auth.internal.lab \
--client-id iac-reverse-tool \
--client-secret <your-secret>
Example output:
Authenticating with Authentik at https://auth.internal.lab...
✓ Authenticated as user: admin@internal.lab
Groups: admins, infra-team
Token stored in .iac-reverse/token
The stored token is automatically used by subsequent scan and generate commands when authentik_token is referenced in your profile.
Supported Providers
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ Provider Platform Type Architecture Resources │
│ ───────────────────────────────────────────────────────────────────── │
│ kubernetes Container Orch. ARM/AArch64 6 types │
│ docker_swarm Container Orch. ARM/AArch64 5 types │
│ synology Storage Appliance ARM/AMD64 5 types │
│ harvester HCI AMD64 4 types │
│ bare_metal Bare Metal AMD64 4 types │
│ windows Windows AMD64 13 types │
│ │
│ Total: 37 resource types across 6 providers │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Resource Types by Provider
| Provider | Resource Types |
|---|---|
| Kubernetes | deployment, service, ingress, config_map, persistent_volume, namespace |
| Docker Swarm | service, network, volume, config, secret |
| Synology | shared_folder, volume, storage_pool, replication_task, user |
| Harvester | virtualmachine, volume, image, network |
| Bare Metal | hardware, bmc_config, network_interface, raid_config |
| Windows | service, scheduled_task, iis_site, iis_app_pool, network_adapter, firewall_rule, installed_software, feature, hyperv_vm, hyperv_switch, dns_record, local_user, local_group |
Troubleshooting
Common Issues
| Problem | Solution |
|---|---|
Terraform binary not found |
Install Terraform and add to PATH |
Authentication failed for provider 'kubernetes' |
Check kubeconfig path and context name |
WinRM is not enabled or unreachable |
Enable WinRM on the target Windows machine |
Connection refused for Docker |
Verify Docker daemon is running and accessible |
Environment variable 'X' is not set |
Export the required env var or add a default in the profile |
Enabling WinRM on Windows targets
# Run on the target Windows machine (as Administrator)
Enable-PSRemoting -Force
winrm set winrm/config/service '@{AllowUnencrypted="false"}'
winrm set winrm/config/service/auth '@{Basic="true"}'
Checking connectivity
# Test Kubernetes access
kubectl --kubeconfig ~/.kube/config --context my-cluster get nodes
# Test Docker Swarm access
docker -H tcp://swarm-manager:2376 node ls
# Test WinRM access (from Linux)
python -c "import winrm; s = winrm.Session('https://win-server:5986/wsman', auth=('user','pass'), transport='ntlm', server_cert_validation='ignore'); print(s.run_ps('hostname').std_out)"
Getting help
# General help
iac-reverse --help
# Command-specific help
iac-reverse scan --help
iac-reverse generate --help
iac-reverse diff --help
iac-reverse validate --help
iac-reverse login --help
Architecture Overview
┌─────────────────────────────────────────────────────────────────────────┐
│ iac-reverse CLI │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Pipeline Engine │ │
│ │ │ │
│ │ ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌───────┐ ┌───────┐ │ │
│ │ │Scanner │─▶│Dependency│─▶│ Code │─▶│ State │─▶│Valida-│ │ │
│ │ │ │ │ Resolver │ │Generator│ │Builder│ │ tor │ │ │
│ │ └────┬────┘ └──────────┘ └─────────┘ └───────┘ └───────┘ │ │
│ │ │ │ │
│ └───────┼──────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────┼──────────────────────────────────────────────────────────┐ │
│ │ │ Provider Plugins │ │
│ │ ┌────┴─────┬──────────┬──────────┬──────────┬──────────┐ │ │
│ │ │Kubernetes│ Docker │ Synology │Harvester │ Windows │ │ │
│ │ │ Plugin │ Plugin │ Plugin │ Plugin │ Plugin │ │ │
│ │ └──────────┴──────────┴──────────┴──────────┴──────────┘ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Incremental Scan Engine │ │
│ │ ┌──────────────┐ ┌────────────────┐ ┌─────────────────────┐ │ │
│ │ │Snapshot Store│ │Change Detector │ │Incremental Updater │ │ │
│ │ └──────────────┘ └────────────────┘ └─────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Tips & Best Practices
- Start small — Scan one provider at a time before combining into multi-provider profiles
- Use resource filters — Limit initial scans to specific resource types to keep output manageable
- Store secrets in env vars — Never hardcode passwords in profile YAML files
- Run diff regularly — Set up a cron job or CI pipeline to detect infrastructure drift
- Review generated code — The tool generates a starting point; review and customize before using in production
- Version control your profiles — Keep scan profiles in git alongside your generated Terraform code
Built with Python 3.11+ • Terraform HCL output • Property-based testing with Hypothesis