🔒 CyberGuard — Multi-Client Cybersecurity Audit Framework

Production-ready · Multi-client · Automated · Report-generating
Deploy on Ubuntu 22.04 VPS in under 10 minutes.

---

📋 Table of Contents

1. Overview
2. Architecture
3. Quick Start
4. Configuration
5. Client Management
6. Running Audits
7. Reports
8. Notifications
9. Cron Scheduling
10. Google Sheets Dashboard
11. Troubleshooting
12. Security Notes
13. Extending the Framework

---

Overview

CyberGuard is a professional, modular cybersecurity audit platform designed for security consultants and MSPs who manage multiple clients. It automates:

• Port & service scanning (Nmap)
• SSL/TLS certificate analysis
• Cyber hygiene scoring (0–100)
• Professional PDF report generation
• Automated email delivery of reports
• Priority alerts via email/WhatsApp for CRITICAL/HIGH findings
• Scan diffing — surfaces new and resolved issues between scans

---

Architecture

cyberguard/
├── scripts/
│   ├── menu.py             ← Main CLI entry point
│   ├── utils.py            ← Shared helpers, config, logging
│   ├── setup_client.py     ← Add / delete clients
│   ├── nmap_scan.py        ← Port & service scanner
│   ├── ssl_checker.py      ← SSL/TLS certificate checker
│   ├── parse_and_diff.py   ← Scoring engine + diff
│   ├── generate_report.py  ← HTML → PDF report builder
│   ├── send_report.py      ← SMTP email delivery
│   ├── notify.py           ← WhatsApp + alert emails
│   ├── sheets_update.py    ← Google Sheets integration
│   └── cron_setup.sh       ← Cron job generator
│
├── clients/
│   └── <client_name>/
│       ├── client.json     ← Client metadata + config
│       ├── scans/          ← Raw scan output (JSON, XML)
│       ├── reports/        ← PDF reports
│       └── logs/           ← Per-client audit logs
│
├── templates/
│   └── report_template.html  ← PDF report HTML template
│
├── logs/                   ← Global framework logs
├── config.json             ← Framework configuration
├── .env                    ← Secrets (SMTP, API keys)
├── requirements.txt
├── install.sh              ← One-command installer
└── cyberguard.sh           ← CLI launcher

---

Quick Start

1. Deploy to Ubuntu 22.04

# Clone or unzip the project
cd /opt
unzip cyberguard.zip  # or: git clone ...
cd cyberguard

# Run installer (requires root)
sudo bash install.sh

2. Configure secrets

nano .env

Fill in at minimum:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your@gmail.com
SMTP_PASSWORD=your_app_password   # Gmail App Password
EMAIL_FROM=your@gmail.com

3. Launch

bash cyberguard.sh

---

Configuration

config.json — Framework Settings

Key	Purpose
framework.clients_dir	Where client folders live
scoring.critical_weight	Score deduction per CRITICAL finding (default: 25)
scoring.high_weight	Score deduction per HIGH finding (default: 15)
nmap.default_arguments	Nmap flags (default: -sV -sC --open -T4)
ssl.warn_days_before_expiry	Days before cert expiry to warn (default: 30)
notifications.send_on_severities	Which severities trigger alerts
report.company_name	Your company name on reports

.env — Secrets & Integrations

# ── SMTP Email (required for reports) ──────────────
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=you@gmail.com
SMTP_PASSWORD=xxxx xxxx xxxx xxxx   # Gmail App Password

# ── WhatsApp Business API (optional) ───────────────
WHATSAPP_ENABLED=false
WHATSAPP_API_TOKEN=your_token
WHATSAPP_FROM_NUMBER=+1234567890

# ── Google Sheets (optional) ───────────────────────
GOOGLE_SHEETS_ENABLED=false
GOOGLE_SHEETS_ID=your_spreadsheet_id

# ── Logging ────────────────────────────────────────
LOG_LEVEL=INFO   # DEBUG | INFO | WARNING | ERROR

Gmail setup:
Go to myaccount.google.com → Security → App Passwords → Generate a password for "Mail".

---

Client Management

Add a Client

From the main menu, select 1. Add new client and fill in:

• Company/client name (becomes the folder ID)
• Target IP(s) or hostname(s) — one per line
• Contact email (for report delivery)
• Contact phone (optional, for WhatsApp alerts)
• Service tier: basic / professional / enterprise

This automatically creates:

clients/
└── acme_corp/
    ├── client.json
    ├── scans/
    ├── reports/
    └── logs/

Delete a Client

Select 2. Delete client → choose client → confirm.

A ZIP backup of all client data is saved to logs/deleted_clients/ before deletion.

Update Payment Status

Select 6. Update client payment status → choose active / suspended / pending.

Audits will be blocked for suspended clients.

Direct JSON Edit

For bulk imports, edit clients/<name>/client.json directly:

{
  "name": "acme_corp",
  "meta": {
    "company": "ACME Corporation",
    "contact_email": "security@acme.com",
    "contact_name": "John Smith",
    "contact_phone": "+1234567890",
    "targets": ["192.168.1.1", "acme.com"],
    "tier": "professional",
    "payment_status": "active",
    "notes": "Quarterly audit client"
  }
}

---

Running Audits

Interactive (Menu)

bash cyberguard.sh
# → Select 4. Run audit for a client
# → Select the client number

Non-Interactive (CLI / Cron)

bash cyberguard.sh --client acme_corp

What Happens During an Audit

[1/6] Nmap port & service scan
      → Identifies open ports, running services, outdated software
[2/6] SSL/TLS certificate check
      → Expiry, weak protocols, cipher suites, HSTS, self-signed
[3/6] Parse results + diff with previous scan
      → Computes score, categorizes findings, finds new/resolved issues
[4/6] Generate PDF report
      → Professional HTML → PDF report saved to client/reports/
[5/6] Send PDF via email
      → Delivered to client contact address
[6/6] Send priority notifications
      → WhatsApp/email for CRITICAL & HIGH findings only

Scoring

Score	Label	Severity
91–100	GOOD	✅
76–90	LOW RISK	🟢
61–75	MEDIUM RISK	🟡
41–60	HIGH RISK	🟠
0–40	CRITICAL RISK	🔴

Deductions per finding:

• CRITICAL: −25 pts
• HIGH: −15 pts
• MEDIUM: −8 pts
• LOW: −3 pts
• INFO: 0 pts

---

Reports

Reports are saved to: clients/<client>/reports/report_<timestamp>.pdf

Report sections:

1. Cover page — Score, client, date, severity summary
2. Executive Summary — Score dashboard, findings counts, diff vs previous
3. Findings Detail — Each finding with description + recommendation
4. Remediation Roadmap — Prioritized table with timelines

PDF Engine priority:

1. WeasyPrint (best quality) — pip install weasyprint
2. pdfkit / wkhtmltopdf — sudo apt install wkhtmltopdf
3. Chromium headless (if installed)
4. HTML fallback (+ stub PDF)

---

Notifications

Email Notifications

Sent automatically for CRITICAL/HIGH findings. Configured via .env.

WhatsApp Business API

1. Set WHATSAPP_ENABLED=true in .env
2. Add your WhatsApp Business API token
3. Add contact_phone to the client's client.json

Messages are sent via the WhatsApp Business Cloud API (Meta/Facebook).
You need a Meta Business account and approved WhatsApp Business API access.

---

Cron Scheduling

Generate cron jobs for automated recurring audits:

bash scripts/cron_setup.sh

Select a schedule (daily/weekly/monthly/custom) and optionally auto-install to crontab.

Manual crontab example:

crontab -e

# CyberGuard — run acme_corp audit every Sunday at 1 AM
0 1 * * 0   bash /opt/cyberguard/cyberguard.sh --client acme_corp >> /opt/cyberguard/logs/cron_acme_corp.log 2>&1

---

Google Sheets Dashboard

1. Create a Google Cloud project and enable the Sheets API
2. Create a Service Account and download JSON credentials
3. Save as credentials/google_service_account.json
4. Share your target spreadsheet with the service account email
5. Set in .env:

   GOOGLE_SHEETS_ENABLED=true
   GOOGLE_SHEETS_ID=your_spreadsheet_id

6. Install: pip install gspread google-auth

Each audit updates a row in the "Audit Dashboard" worksheet.

---

Troubleshooting

"nmap: command not found"

sudo apt-get install -y nmap

"python-nmap not installed" (falls back to subprocess)

pip install python-nmap

PDF generation falls back to HTML

# Option A: WeasyPrint (recommended)
pip install weasyprint

# Option B: wkhtmltopdf
sudo apt-get install -y wkhtmltopdf
pip install pdfkit

SMTP authentication error

• For Gmail: use an App Password, not your regular password
• Enable 2FA on your Google account first
• Generate App Password: myaccount.google.com → Security → App Passwords

Scan hangs on large networks

Reduce scope in config.json:

"nmap": {
  "default_arguments": "-sV --open -T3 --top-ports 100",
  "timeout": 120
}

Permissions error on /clients/

sudo chown -R $USER:$USER /opt/cyberguard/clients
chmod -R 755 /opt/cyberguard/clients

Check logs

# Global framework log
tail -f logs/cyberguard_$(date +%Y%m).log

# Per-client log
tail -f clients/acme_corp/logs/acme_corp_$(date +%Y%m).log

---

Security Notes

• Never commit .env to version control. It's in .gitignore.
• The credentials/ folder has chmod 700 permissions.
• Client data contains potentially sensitive scan results — restrict server access.
• Reports are emailed as attachments — use TLS-enabled SMTP.
• Nmap scans generate network traffic that may trigger IDS/IPS on client networks — always obtain written authorization before scanning.
• scanme.nmap.org is the only public host authorized for nmap testing.

---

Extending the Framework

Add a New Scanner

1. Create scripts/my_scanner.py with a run_my_scan(target, scan_dir, timestamp, config) -> list[dict] function
2. Return findings using the make_finding(...) factory
3. Call it from menu.py's run_audit() function

Custom Report Sections

Edit templates/report_template.html — it uses {{variable}} placeholders populated by generate_report.py.

Custom Scoring

Edit config.json:

"scoring": {
  "critical_weight": 30,
  "high_weight": 20,
  "medium_weight": 10,
  "low_weight": 5
}

---

License

This software is proprietary. All rights reserved.
Unauthorized redistribution or resale is prohibited.

---

CyberGuard Security Platform v1.0.0
Built for Ubuntu 22.04 LTS · Python 3.10+