CF PenTestIQ

Web application for performing penetration tests on SaaS services using remote Kali Linux and generating professional HTML reports with AI analysis.

🚀 Quick Start

Option 1: Docker (Recommended)

Prerequisites:

• Docker Engine 20.10+
• Docker Compose 2.0+

Steps:

1. Configure environment variables:

# Copy example file
cp env.example .env

# Edit .env and configure SECRET_KEY and other variables

2. Start all services:

docker-compose up -d

This will start:

• PostgreSQL: Database
• Redis: Cache and message broker
• Web: Django application
• Celery: Worker for asynchronous tasks
• Kali (optional): Kali Linux in Docker

3. Create superuser (first time):

docker-compose exec web python manage.py createsuperuser

Note: Default credentials are automatically created: admin / admin

4. Access the application:

• Open: http://localhost:7000
• Login with superuser credentials

Useful commands:

# Windows - Start everything
run.bat

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Rebuild images
docker-compose build --no-cache

# Execute Django commands
docker-compose exec web python manage.py <command>

Option 2: Local Installation

Prerequisites:

• Python 3.8+
• PostgreSQL or SQLite
• Redis

Steps:

1. Install dependencies:

pip install -r requirements.txt

2. Configure database:

python manage.py makemigrations
python manage.py migrate

3. Create administrator user:

python manage.py createsuperuser

4. Start Redis:

# Windows/Linux/Mac
docker run -d -p 6379:6379 redis:alpine

5. Start web server:

# Windows
run.bat

# Linux/Mac
daphne -p 7000 pentest_web.asgi:application

6. Access the application:

• Open: http://localhost:7000
• Login with superuser credentials

🐳 Docker - Complete Guide

Initial Configuration

1. Configure Environment Variables

Copy the example file and configure the variables:

cp env.example .env

Edit the .env file and configure:

• SECRET_KEY: Django secret key (generate a new one for production)
• DB_PASSWORD: PostgreSQL database password
• ALLOWED_HOSTS: Allowed hosts (add domain in production)

Useful Docker Commands

View Logs:

# All services
docker-compose logs -f

# Web only
docker-compose logs -f web

# Celery only
docker-compose logs -f celery

# Kali only
docker-compose logs -f kali

Stop Services:

# Stop without removing volumes
docker-compose stop

# Stop and remove containers (keeps volumes)
docker-compose down

# Stop and remove everything (including volumes)
docker-compose down -v

Rebuild Images:

# Rebuild without cache
docker-compose build --no-cache

# Rebuild and restart
docker-compose up -d --build

Execute Django Commands:

# Migrations
docker-compose exec web python manage.py migrate

# Create migrations
docker-compose exec web python manage.py makemigrations

# Django shell
docker-compose exec web python manage.py shell

# Collect static files
docker-compose exec web python manage.py collectstatic

Access Database:

# PostgreSQL shell
docker-compose exec db psql -U pentest_user -d pentest_db

# Redis CLI
docker-compose exec redis redis-cli

Volume Structure

The following volumes are created for persistence:

• postgres_data: PostgreSQL database data
• static_volume: Collected static files
• media_volume: Media files
• reports_volume: Generated reports
• logs_volume: Log files
• kali_data: Kali root user data
• kali_tools: Custom Kali tools

Development

For development with hot-reload, use volumes:

# docker-compose.override.yml (create this file)
version: '3.8'
services:
  web:
    volumes:
      - .:/app
    environment:
      - DEBUG=True

Production

For production, consider:

1. Change SECRET_KEY in .env
2. Configure ALLOWED_HOSTS with the real domain
3. Use HTTPS (configure nginx as reverse proxy)
4. Regular backup of volumes
5. Monitor logs and resources
6. Disable DEBUG (DEBUG=False)

Docker Troubleshooting

Container doesn't start:

# View detailed logs
docker-compose logs web

# Check if ports are free
netstat -an | grep 7000
netstat -an | grep 5432
netstat -an | grep 6379

Database connection error:

# Check if PostgreSQL is running
docker-compose ps db

# View PostgreSQL logs
docker-compose logs db

Permission error:

# Adjust permissions (Linux/Mac)
sudo chown -R $USER:$USER .

Clean everything and restart:

# Stop and remove everything
docker-compose down -v

# Remove images
docker-compose rm -f

# Rebuild from scratch
docker-compose build --no-cache
docker-compose up -d

🐧 Kali Linux in Docker

This project supports running Kali Linux in Docker, facilitating setup and isolation of the pentesting environment.

Start Kali in Docker

# Build and start Kali container
docker-compose build kali
docker-compose up -d kali

# View logs
docker-compose logs -f kali

Configure SSH on Kali

The Kali container is configured with:

• Host: kali (service name in docker-compose) or localhost (if accessing externally)
• Port: 22 (internal) or 2222 (external)
• Username: root
• Password: kali (⚠️ CHANGE IN PRODUCTION!)

Change Root Password:

# Enter container
docker-compose exec kali bash

# Change password
passwd root

# Or via single command
docker-compose exec kali bash -c "echo 'root:YOUR_NEW_PASSWORD' | chpasswd"

Configure in Application

1. Access application: http://localhost:7000
2. Go to Settings
3. Configure SSH Connection:
   • Host: kali (if in same docker-compose) or localhost (if accessing externally)
   • Port: 22 (internal) or 2222 (external)
   • Username: root
   • Password: kali (or the password you set)
   • Key File: (optional) leave empty or use ~/.ssh/id_rsa

Note: SSH connection is automatically configured with Docker Kali defaults when the superuser is created.

Access Kali Container

# Enter container interactively
docker-compose exec kali bash

# Execute commands
docker-compose exec kali nmap --version
docker-compose exec kali nikto -Version

Install Additional Tools

# Enter container
docker-compose exec kali bash

# Install specific tools
apt-get update
apt-get install -y <tool-name>

# Example: install additional tools
apt-get install -y aircrack-ng burpsuite

Kali Troubleshooting

SSH doesn't connect:

# Check if SSH is running
docker-compose exec kali service ssh status

# Restart SSH
docker-compose exec kali service ssh restart

# View container logs
docker-compose logs kali

Tools not found:

# Check installation
docker-compose exec kali which nmap
docker-compose exec kali which nikto

# Reinstall tools
docker-compose exec kali apt-get update
docker-compose exec kali apt-get install -y kali-linux-headless

Rebuild Kali image:

# Rebuild with cache
docker-compose build kali

# Rebuild without cache
docker-compose build --no-cache kali

# Restart
docker-compose up -d kali

Kali Security

⚠️ IMPORTANT:

• The Kali container uses default password kali - CHANGE IN PRODUCTION!
• Configure SSH key authentication instead of password
• Do not expose SSH port publicly
• Use only in isolated/development environments

Configure SSH Key:

# Generate SSH key (on host)
ssh-keygen -t rsa -b 4096 -f ~/.ssh/kali_docker_key

# Copy key to container
docker cp ~/.ssh/kali_docker_key.pub pentest_kali:/root/.ssh/authorized_keys

# Configure permissions
docker-compose exec kali chmod 600 /root/.ssh/authorized_keys
docker-compose exec kali chmod 700 /root/.ssh

# Disable password authentication
docker-compose exec kali sed -i 's/PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
docker-compose exec kali service ssh restart

Use External Kali

If you prefer to use an external Kali Linux (not in Docker), simply don't start the kali service:

# Don't start Kali
docker-compose up -d db redis web celery

# Configure in application with external Kali IP/hostname

📋 How to Use

Initial Configuration

1. Configure SSH (Kali Linux):

   • Go to Settings
   • Fill in SSH connection data:
     • Host: Kali Linux IP or kali (if using Docker)
     • Port: 22 (default) or 2222 (if using Docker externally)
     • Username: kali or root
     • Password: (Kali password)
   • Save

2. Configure Company:

   • In Settings, fill in "Company" field
   • This appears in generated reports

Create and Execute a Scan

1. Create Scan:

   • Click "New Scan"
   • Enter Target (URL or IP): https://example.com
   • Select Scanners (check the ones you want to execute)
   • Choose Execution Mode:
     • Sequential: One at a time
     • Parallel: All at the same time
     • Hybrid: Intelligent (recommended)
   • Click "Create Scan"

2. Start Scan:

   • On the scan page, click "▶️ Start Scan"
   • View real-time progress
   • Wait for completion

3. View Results:

   • Click "View Results"
   • View details of each scanner
   • Click on scanner to see full output

4. Generate Report:

   • On results page, click "Generate Report"
   • Wait for generation (may take time)
   • Click "📥 Download Report" to download HTML

Recover Stuck Scan

If a scan gets stuck in "Running":

• Click "⚠️ Reset & Restart"
• Confirm reset
• Click "▶️ Start Scan" again

Restart Failed Scan

If a scan fails:

• The button changes to "🔄 Restart Scan"
• Click to restart automatically

🛠️ Requirements

• Python 3.8+
• PostgreSQL (or SQLite for development)
• Redis (via Docker recommended)
• Kali Linux accessible via SSH (can be Docker or external)
• Tools installed on Kali:
  • nmap, nikto, sqlmap, dirb, gobuster
  • OWASP ZAP, WPScan, SSLyze, WhatWeb, Metasploit

Note: For WhatWeb, use GitHub installation in /opt/whatweb/ instead of apt package.

📊 Available Scanners

Scanner	Function
Nmap	Port and service scanning
Nikto	Web vulnerability scanning
SQLMap	SQL injection testing
Dirb	Directory brute force
Gobuster	Directory brute force (Go)
OWASP ZAP	Web security scanner
WPScan	WordPress scanning
SSLyze	SSL/TLS analysis
WhatWeb	Web technology identification
Metasploit	Penetration testing framework

⚙️ Execution Modes

Sequential

Executes one scanner at a time, in the selected order.

Parallel

Executes all scanners simultaneously.

Hybrid (Recommended)

• Respects dependencies (e.g., nmap before others)
• Groups scanners for parallel execution
• Optimizes time while maintaining correct order

📄 Reports

Reports include:

• Executive Summary with AI analysis
• Risk Assessment (HIGH/MEDIUM/LOW/MINIMAL)
• Detailed Results from each scanner
• Remediation Plan with priority actions
• Execution Statistics

🔧 Troubleshooting

Scan doesn't start

• Check if Redis is running
• Check SSH connection in Settings
• Check if scanners are installed on Kali

Error 403 when starting scan

• Refresh the page (F5)
• Check if you are authenticated

Scan stuck in "Running"

• Click "⚠️ Reset & Restart"
• Restart the scan

WebSocket doesn't connect

• Check if Redis is running
• Check server logs

📝 Project Structure

CF_PenTestIQ/
├── manage.py                 # Django management script
├── Dockerfile               # Docker image
├── Dockerfile.kali          # Docker image for Kali
├── docker-compose.yml       # Docker orchestration
├── docker-entrypoint.sh     # Initialization script
├── env.example              # Environment variables example
├── pentest_web/             # Project configuration
├── apps/
│   ├── accounts/            # Authentication
│   └── core/                # Main application
├── modules/                 # Existing modules
│   ├── scanners/            # Scanner modules
│   ├── ssh_client.py        # SSH client
│   └── ai_analyzer.py       # AI analysis
├── templates/               # HTML templates
├── static/                  # Static files
├── reports/                 # Generated reports
├── logs/                    # Log files
└── data/                    # Application data

🔐 Security

⚠️ WARNING: This tool is only for use on systems you own or have explicit authorization to test.

Security Recommendations:

• Change default passwords in production
• Use SSH key authentication
• Do not expose SSH ports publicly
• Use HTTPS in production
• Regular data backups
• Keep dependencies updated

📚 Environment Variables

See env.example for all available variables.

Main variables:

• SECRET_KEY: Django secret key (required)
• DEBUG: Debug mode (True/False)
• ALLOWED_HOSTS: Allowed hosts (comma-separated)
• DB_*: Database configuration
• REDIS_HOST, REDIS_PORT: Redis configuration
• CELERY_*: Celery configuration

🆘 Support

For problems or questions:

1. Check server logs
2. Check SSH connection
3. Check if Redis is running
4. Check if scanners are installed on Kali Linux
5. Consult Troubleshooting section above

---

Version: 1.4.0
Last update: December 2025