cisco-conf-generator/README.md

# Cisco Config Builder SaaS

Production-ready network device configuration management platform.

## Overview

**Cisco Config Builder** is a web-based SaaS for managing Cisco device configurations through an intuitive GUI. Build, validate, and deploy network configs to devices securely via SSH.

### Key Features
- 🎨 Intuitive configuration builder GUI
- ✅ Real-time configuration validation
- 📊 Live CLI preview
- 🔒 Secure SSH push with confirmation
- 📝 Complete audit logging
- 🔄 Rollback capability
- 🧪 Dry-run mode

### Tech Stack
- **Backend**: FastAPI + SQLAlchemy + PostgreSQL
- **Frontend**: React + TypeScript
- **Network**: Netmiko + SSH
- **Auth**: JWT
- **DevOps**: Docker + Docker Compose

## Quick Start

### Prerequisites
- Docker & Docker Compose
- Python 3.11+ (for local development)
- Node.js 20+ (for local development)

### Development Setup

```bash
# Backend
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
export DATABASE_URL="postgresql://cisco_user:cisco_pass@localhost:5432/cisco_builder"
python run.py

# Frontend (new terminal)
cd frontend
npm install
npm run dev

# Database (PostgreSQL)
# Use docker-compose from docker/ folder or install PostgreSQL locally
docker-compose -f docker/docker-compose.yml up postgres
```

### Production Deployment

```bash
# Build and run all services
./startup.sh

# Or manually:
docker-compose -f docker/docker-compose.yml up -d
```

## Architecture

### Backend Structure
```
backend/
├── app/
│   ├── core/          # Config, database, security
│   ├── models/        # SQLAlchemy ORM models
│   ├── schemas/       # Pydantic request/response schemas
│   ├── routers/       # API endpoints (auth, projects, devices, etc.)
│   ├── cli/           # CLI generation engine
│   ├── validation/    # Config validator
│   ├── ssh/           # Netmiko SSH executor
│   └── main.py        # FastAPI app
├── tests/             # Unit and integration tests
└── requirements.txt
```

### Frontend Structure
```
frontend/
├── src/
│   ├── components/    # React components (wizard, preview, modals)
│   ├── pages/         # Page components
│   ├── services/      # API client
│   ├── hooks/         # Custom hooks
│   ├── types/         # TypeScript types
│   └── styles/        # Global styles
└── package.json
```

## API Documentation

### Authentication
```
POST /api/v1/auth/register
POST /api/v1/auth/login
```

### Projects
```
GET /api/v1/projects
POST /api/v1/projects
GET /api/v1/projects/{id}
PUT /api/v1/projects/{id}
DELETE /api/v1/projects/{id}
```

### Devices
```
GET /api/v1/devices
POST /api/v1/devices
GET /api/v1/devices/{id}
PUT /api/v1/devices/{id}
DELETE /api/v1/devices/{id}
```

### Configurations
```
GET /api/v1/configurations
POST /api/v1/configurations
GET /api/v1/configurations/{id}
PUT /api/v1/configurations/{id}
POST /api/v1/configurations/{id}/validate
POST /api/v1/configurations/{id}/generate
POST /api/v1/configurations/{id}/push
```

Full OpenAPI documentation available at: `http://localhost:8000/api/v1/docs`

## Security Model

### Credentials
- **Never stored plaintext** - Use encryption (Fernet) for in-transit encryption only
- **SSH credentials passed at push time** - Not stored in database
- **Optional encrypted storage** for trusted environments (Vault recommended)

### Access Control
- JWT-based authentication
- Per-project ownership
- User isolation

### Audit Trail
- All push operations logged to `push_logs` table
- Timestamps, usernames, commands, device output
- Pre-push backup (running-config)
- Rollback metadata

### SSH Safety
- Dry-run mode (validation only)
- Explicit confirmation required before push
- Connection timeout: 30s
- Command preview before execution
- Device output logged

## Configuration Data Model

Example `config_data` JSON:

```json
{
  "hostname": "SWITCH-01",
  "vlans": [
    {"id": 10, "name": "USERS"},
    {"id": 20, "name": "SERVERS"}
  ],
  "interfaces": [
    {
      "name": "GigabitEthernet0/1",
      "description": "Access Port",
      "type": "access",
      "vlan": 10,
      "enabled": true
    },
    {
      "name": "GigabitEthernet0/24",
      "description": "Uplink",
      "type": "trunk",
      "trunk_vlans": [10, 20],
      "enabled": true
    }
  ],
  "routes": [
    {
      "destination": "10.0.0.0/24",
      "gateway": "192.168.1.1",
      "metric": 1
    }
  ]
}
```

## Validation Engine

The validator checks for:
- ✅ VLAN ID range (1-4094)
- ✅ No duplicate VLANs
- ✅ Interface VLAN references
- ✅ IP address overlaps
- ✅ NAT configuration completeness
- ⚠️ Warnings for trunk VLAN mismatches, missing ACL rules, etc.

## Netmiko Integration

Supported device types:
- `cisco_ios` - IOS devices
- `cisco_xe` - IOS-XE devices
- `cisco_xr` - IOS-XR devices

Commands executed in order:
1. Backup running-config (optional)
2. Execute configuration commands
3. Verify success
4. Save to startup-config
5. Log to audit trail

## Testing

```bash
# Run tests
cd backend
pytest

# With coverage
pytest --cov=app tests/
```

## Roadmap

### MVP (Current)
- ✅ Basic device management
- ✅ VLAN, interface, routing config
- ✅ CLI generation
- ✅ Validation
- ✅ SSH push

### V1
- [ ] Multi-device batch operations
- [ ] Config templates & macros
- [ ] CCNA/CCNP lab presets
- [ ] IPv6 support
- [ ] Export to PDF/TXT
- [ ] Config diff/history
- [ ] Role-based access (RBAC)

### V2
- [ ] Multi-vendor support (Juniper, Arista, etc.)
- [ ] API-driven config sync
- [ ] Slack/Teams integration
- [ ] Advanced scheduling
- [ ] Terraform export

## License

Proprietary - Cisco Config Builder SaaS

## Support

For issues, questions, or feature requests:
- 📧 support@ciscoconfigbuilder.io
- 🐛 GitHub Issues
- 💬 Community Slack

---

**Built with ❤️ for network engineers**