Complete Phase 1: Foundation - Flask web application infrastructure

Implement complete database schema and Flask application structure for
SneakyScan web interface. This establishes the foundation for web-based
scan management, scheduling, and visualization.

Database & ORM:
- Add 11 SQLAlchemy models for comprehensive scan data storage
  (Scan, ScanSite, ScanIP, ScanPort, ScanService, ScanCertificate,
  ScanTLSVersion, Schedule, Alert, AlertRule, Setting)
- Configure Alembic migrations system with initial schema migration
- Add init_db.py script for database initialization and password setup
- Support both migration-based and direct table creation

Settings System:
- Implement SettingsManager with automatic encryption for sensitive values
- Add Fernet encryption for SMTP passwords and API tokens
- Implement PasswordManager with bcrypt password hashing (work factor 12)
- Initialize default settings for SMTP, authentication, and retention

Flask Application:
- Create Flask app factory pattern with scoped session management
- Add 4 API blueprints: scans, schedules, alerts, settings
- Implement functional Settings API (GET/PUT/DELETE endpoints)
- Add CORS support, error handlers, and request/response logging
- Configure development and production logging to file and console

Docker & Deployment:
- Update Dockerfile to install Flask dependencies
- Add docker-compose-web.yml for web application deployment
- Configure volume mounts for database, output, and logs persistence
- Expose port 5000 for Flask web server

Testing & Validation:
- Add validate_phase1.py script to verify all deliverables
- Validate directory structure, Python syntax, models, and endpoints
- All validation checks passing

Documentation:
- Add PHASE1_COMPLETE.md with comprehensive Phase 1 summary
- Update ROADMAP.md with Phase 1 completion status
- Update .gitignore to exclude database files and documentation

Files changed: 21 files
- New: web/ directory with complete Flask app structure
- New: migrations/ with Alembic configuration
- New: requirements-web.txt with Flask dependencies
- Modified: Dockerfile, ROADMAP.md, .gitignore
This commit is contained in:
2025-11-13 23:59:23 -06:00
parent e29c839d80
commit 986c0d3d17
22 changed files with 3138 additions and 42 deletions

0
web/api/__init__.py Normal file
View File

137
web/api/alerts.py Normal file
View File

@@ -0,0 +1,137 @@
"""
Alerts API blueprint.
Handles endpoints for viewing alert history and managing alert rules.
"""
from flask import Blueprint, jsonify, request
bp = Blueprint('alerts', __name__)
@bp.route('', methods=['GET'])
def list_alerts():
"""
List recent alerts.
Query params:
page: Page number (default: 1)
per_page: Items per page (default: 20)
alert_type: Filter by alert type
severity: Filter by severity (info, warning, critical)
start_date: Filter alerts after this date
end_date: Filter alerts before this date
Returns:
JSON response with alerts list
"""
# TODO: Implement in Phase 4
return jsonify({
'alerts': [],
'total': 0,
'page': 1,
'per_page': 20,
'message': 'Alerts list endpoint - to be implemented in Phase 4'
})
@bp.route('/rules', methods=['GET'])
def list_alert_rules():
"""
List all alert rules.
Returns:
JSON response with alert rules
"""
# TODO: Implement in Phase 4
return jsonify({
'rules': [],
'message': 'Alert rules list endpoint - to be implemented in Phase 4'
})
@bp.route('/rules', methods=['POST'])
def create_alert_rule():
"""
Create a new alert rule.
Request body:
rule_type: Type of alert rule
threshold: Threshold value (e.g., days for cert expiry)
enabled: Whether rule is active (default: true)
email_enabled: Send email for this rule (default: false)
Returns:
JSON response with created rule ID
"""
# TODO: Implement in Phase 4
data = request.get_json() or {}
return jsonify({
'rule_id': None,
'status': 'not_implemented',
'message': 'Alert rule creation endpoint - to be implemented in Phase 4',
'data': data
}), 501
@bp.route('/rules/<int:rule_id>', methods=['PUT'])
def update_alert_rule(rule_id):
"""
Update an existing alert rule.
Args:
rule_id: Alert rule ID to update
Request body:
threshold: Threshold value (optional)
enabled: Whether rule is active (optional)
email_enabled: Send email for this rule (optional)
Returns:
JSON response with update status
"""
# TODO: Implement in Phase 4
data = request.get_json() or {}
return jsonify({
'rule_id': rule_id,
'status': 'not_implemented',
'message': 'Alert rule update endpoint - to be implemented in Phase 4',
'data': data
}), 501
@bp.route('/rules/<int:rule_id>', methods=['DELETE'])
def delete_alert_rule(rule_id):
"""
Delete an alert rule.
Args:
rule_id: Alert rule ID to delete
Returns:
JSON response with deletion status
"""
# TODO: Implement in Phase 4
return jsonify({
'rule_id': rule_id,
'status': 'not_implemented',
'message': 'Alert rule deletion endpoint - to be implemented in Phase 4'
}), 501
# Health check endpoint
@bp.route('/health', methods=['GET'])
def health_check():
"""
Health check endpoint for monitoring.
Returns:
JSON response with API health status
"""
return jsonify({
'status': 'healthy',
'api': 'alerts',
'version': '1.0.0-phase1'
})

150
web/api/scans.py Normal file
View File

@@ -0,0 +1,150 @@
"""
Scans API blueprint.
Handles endpoints for triggering scans, listing scan history, and retrieving
scan results.
"""
from flask import Blueprint, current_app, jsonify, request
bp = Blueprint('scans', __name__)
@bp.route('', methods=['GET'])
def list_scans():
"""
List all scans with pagination.
Query params:
page: Page number (default: 1)
per_page: Items per page (default: 20, max: 100)
status: Filter by status (running, completed, failed)
Returns:
JSON response with scans list and pagination info
"""
# TODO: Implement in Phase 2
return jsonify({
'scans': [],
'total': 0,
'page': 1,
'per_page': 20,
'message': 'Scans endpoint - to be implemented in Phase 2'
})
@bp.route('/<int:scan_id>', methods=['GET'])
def get_scan(scan_id):
"""
Get details for a specific scan.
Args:
scan_id: Scan ID
Returns:
JSON response with scan details
"""
# TODO: Implement in Phase 2
return jsonify({
'scan_id': scan_id,
'message': 'Scan detail endpoint - to be implemented in Phase 2'
})
@bp.route('', methods=['POST'])
def trigger_scan():
"""
Trigger a new scan.
Request body:
config_file: Path to YAML config file
Returns:
JSON response with scan_id and status
"""
# TODO: Implement in Phase 2
data = request.get_json() or {}
config_file = data.get('config_file')
return jsonify({
'scan_id': None,
'status': 'not_implemented',
'message': 'Scan trigger endpoint - to be implemented in Phase 2',
'config_file': config_file
}), 501 # Not Implemented
@bp.route('/<int:scan_id>', methods=['DELETE'])
def delete_scan(scan_id):
"""
Delete a scan and its associated files.
Args:
scan_id: Scan ID to delete
Returns:
JSON response with deletion status
"""
# TODO: Implement in Phase 2
return jsonify({
'scan_id': scan_id,
'status': 'not_implemented',
'message': 'Scan deletion endpoint - to be implemented in Phase 2'
}), 501
@bp.route('/<int:scan_id>/status', methods=['GET'])
def get_scan_status(scan_id):
"""
Get current status of a running scan.
Args:
scan_id: Scan ID
Returns:
JSON response with scan status and progress
"""
# TODO: Implement in Phase 2
return jsonify({
'scan_id': scan_id,
'status': 'not_implemented',
'progress': '0%',
'message': 'Scan status endpoint - to be implemented in Phase 2'
})
@bp.route('/<int:scan_id1>/compare/<int:scan_id2>', methods=['GET'])
def compare_scans(scan_id1, scan_id2):
"""
Compare two scans and show differences.
Args:
scan_id1: First scan ID
scan_id2: Second scan ID
Returns:
JSON response with comparison results
"""
# TODO: Implement in Phase 4
return jsonify({
'scan_id1': scan_id1,
'scan_id2': scan_id2,
'diff': {},
'message': 'Scan comparison endpoint - to be implemented in Phase 4'
})
# Health check endpoint
@bp.route('/health', methods=['GET'])
def health_check():
"""
Health check endpoint for monitoring.
Returns:
JSON response with API health status
"""
return jsonify({
'status': 'healthy',
'api': 'scans',
'version': '1.0.0-phase1'
})

150
web/api/schedules.py Normal file
View File

@@ -0,0 +1,150 @@
"""
Schedules API blueprint.
Handles endpoints for managing scheduled scans including CRUD operations
and manual triggering.
"""
from flask import Blueprint, jsonify, request
bp = Blueprint('schedules', __name__)
@bp.route('', methods=['GET'])
def list_schedules():
"""
List all schedules.
Returns:
JSON response with schedules list
"""
# TODO: Implement in Phase 3
return jsonify({
'schedules': [],
'message': 'Schedules list endpoint - to be implemented in Phase 3'
})
@bp.route('/<int:schedule_id>', methods=['GET'])
def get_schedule(schedule_id):
"""
Get details for a specific schedule.
Args:
schedule_id: Schedule ID
Returns:
JSON response with schedule details
"""
# TODO: Implement in Phase 3
return jsonify({
'schedule_id': schedule_id,
'message': 'Schedule detail endpoint - to be implemented in Phase 3'
})
@bp.route('', methods=['POST'])
def create_schedule():
"""
Create a new schedule.
Request body:
name: Schedule name
config_file: Path to YAML config
cron_expression: Cron-like schedule expression
Returns:
JSON response with created schedule ID
"""
# TODO: Implement in Phase 3
data = request.get_json() or {}
return jsonify({
'schedule_id': None,
'status': 'not_implemented',
'message': 'Schedule creation endpoint - to be implemented in Phase 3',
'data': data
}), 501
@bp.route('/<int:schedule_id>', methods=['PUT'])
def update_schedule(schedule_id):
"""
Update an existing schedule.
Args:
schedule_id: Schedule ID to update
Request body:
name: Schedule name (optional)
config_file: Path to YAML config (optional)
cron_expression: Cron-like schedule expression (optional)
enabled: Whether schedule is active (optional)
Returns:
JSON response with update status
"""
# TODO: Implement in Phase 3
data = request.get_json() or {}
return jsonify({
'schedule_id': schedule_id,
'status': 'not_implemented',
'message': 'Schedule update endpoint - to be implemented in Phase 3',
'data': data
}), 501
@bp.route('/<int:schedule_id>', methods=['DELETE'])
def delete_schedule(schedule_id):
"""
Delete a schedule.
Args:
schedule_id: Schedule ID to delete
Returns:
JSON response with deletion status
"""
# TODO: Implement in Phase 3
return jsonify({
'schedule_id': schedule_id,
'status': 'not_implemented',
'message': 'Schedule deletion endpoint - to be implemented in Phase 3'
}), 501
@bp.route('/<int:schedule_id>/trigger', methods=['POST'])
def trigger_schedule(schedule_id):
"""
Manually trigger a scheduled scan.
Args:
schedule_id: Schedule ID to trigger
Returns:
JSON response with triggered scan ID
"""
# TODO: Implement in Phase 3
return jsonify({
'schedule_id': schedule_id,
'scan_id': None,
'status': 'not_implemented',
'message': 'Manual schedule trigger endpoint - to be implemented in Phase 3'
}), 501
# Health check endpoint
@bp.route('/health', methods=['GET'])
def health_check():
"""
Health check endpoint for monitoring.
Returns:
JSON response with API health status
"""
return jsonify({
'status': 'healthy',
'api': 'schedules',
'version': '1.0.0-phase1'
})

267
web/api/settings.py Normal file
View File

@@ -0,0 +1,267 @@
"""
Settings API blueprint.
Handles endpoints for managing application settings including SMTP configuration,
authentication, and system preferences.
"""
from flask import Blueprint, current_app, jsonify, request
from web.utils.settings import PasswordManager, SettingsManager
bp = Blueprint('settings', __name__)
def get_settings_manager():
"""Get SettingsManager instance with current DB session."""
return SettingsManager(current_app.db_session)
@bp.route('', methods=['GET'])
def get_settings():
"""
Get all settings (sanitized - encrypted values masked).
Returns:
JSON response with all settings
"""
try:
settings_manager = get_settings_manager()
settings = settings_manager.get_all(decrypt=False, sanitize=True)
return jsonify({
'status': 'success',
'settings': settings
})
except Exception as e:
current_app.logger.error(f"Failed to retrieve settings: {e}")
return jsonify({
'status': 'error',
'message': 'Failed to retrieve settings'
}), 500
@bp.route('', methods=['PUT'])
def update_settings():
"""
Update multiple settings at once.
Request body:
settings: Dictionary of setting key-value pairs
Returns:
JSON response with update status
"""
# TODO: Add authentication in Phase 2
data = request.get_json() or {}
settings_dict = data.get('settings', {})
if not settings_dict:
return jsonify({
'status': 'error',
'message': 'No settings provided'
}), 400
try:
settings_manager = get_settings_manager()
# Update each setting
for key, value in settings_dict.items():
settings_manager.set(key, value)
return jsonify({
'status': 'success',
'message': f'Updated {len(settings_dict)} settings'
})
except Exception as e:
current_app.logger.error(f"Failed to update settings: {e}")
return jsonify({
'status': 'error',
'message': 'Failed to update settings'
}), 500
@bp.route('/<string:key>', methods=['GET'])
def get_setting(key):
"""
Get a specific setting by key.
Args:
key: Setting key
Returns:
JSON response with setting value
"""
try:
settings_manager = get_settings_manager()
value = settings_manager.get(key)
if value is None:
return jsonify({
'status': 'error',
'message': f'Setting "{key}" not found'
}), 404
# Sanitize if encrypted key
if settings_manager._should_encrypt(key):
value = '***ENCRYPTED***'
return jsonify({
'status': 'success',
'key': key,
'value': value
})
except Exception as e:
current_app.logger.error(f"Failed to retrieve setting {key}: {e}")
return jsonify({
'status': 'error',
'message': 'Failed to retrieve setting'
}), 500
@bp.route('/<string:key>', methods=['PUT'])
def update_setting(key):
"""
Update a specific setting.
Args:
key: Setting key
Request body:
value: New value for the setting
Returns:
JSON response with update status
"""
# TODO: Add authentication in Phase 2
data = request.get_json() or {}
value = data.get('value')
if value is None:
return jsonify({
'status': 'error',
'message': 'No value provided'
}), 400
try:
settings_manager = get_settings_manager()
settings_manager.set(key, value)
return jsonify({
'status': 'success',
'message': f'Setting "{key}" updated'
})
except Exception as e:
current_app.logger.error(f"Failed to update setting {key}: {e}")
return jsonify({
'status': 'error',
'message': 'Failed to update setting'
}), 500
@bp.route('/<string:key>', methods=['DELETE'])
def delete_setting(key):
"""
Delete a setting.
Args:
key: Setting key to delete
Returns:
JSON response with deletion status
"""
# TODO: Add authentication in Phase 2
try:
settings_manager = get_settings_manager()
deleted = settings_manager.delete(key)
if not deleted:
return jsonify({
'status': 'error',
'message': f'Setting "{key}" not found'
}), 404
return jsonify({
'status': 'success',
'message': f'Setting "{key}" deleted'
})
except Exception as e:
current_app.logger.error(f"Failed to delete setting {key}: {e}")
return jsonify({
'status': 'error',
'message': 'Failed to delete setting'
}), 500
@bp.route('/password', methods=['POST'])
def set_password():
"""
Set the application password.
Request body:
password: New password
Returns:
JSON response with status
"""
# TODO: Add current password verification in Phase 2
data = request.get_json() or {}
password = data.get('password')
if not password:
return jsonify({
'status': 'error',
'message': 'No password provided'
}), 400
if len(password) < 8:
return jsonify({
'status': 'error',
'message': 'Password must be at least 8 characters'
}), 400
try:
settings_manager = get_settings_manager()
PasswordManager.set_app_password(settings_manager, password)
return jsonify({
'status': 'success',
'message': 'Password updated successfully'
})
except Exception as e:
current_app.logger.error(f"Failed to set password: {e}")
return jsonify({
'status': 'error',
'message': 'Failed to set password'
}), 500
@bp.route('/test-email', methods=['POST'])
def test_email():
"""
Test email configuration by sending a test email.
Returns:
JSON response with test result
"""
# TODO: Implement in Phase 4 (email support)
return jsonify({
'status': 'not_implemented',
'message': 'Email testing endpoint - to be implemented in Phase 4'
}), 501
# Health check endpoint
@bp.route('/health', methods=['GET'])
def health_check():
"""
Health check endpoint for monitoring.
Returns:
JSON response with API health status
"""
return jsonify({
'status': 'healthy',
'api': 'settings',
'version': '1.0.0-phase1'
})