From 3c740268c465b58ff2966c4ecf8f6413db215bdb Mon Sep 17 00:00:00 2001 From: Phillip Tarrant Date: Tue, 18 Nov 2025 13:23:06 -0600 Subject: [PATCH] updated API docs --- docs/API_REFERENCE.md | 385 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 333 insertions(+), 52 deletions(-) diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index a7a7c49..f5bdbeb 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -1,6 +1,6 @@ # SneakyScanner Web API Reference -**Version:** 4.0 (Phase 4) +**Version:** 5.0 (Phase 5) **Base URL:** `http://localhost:5000` **Authentication:** Session-based (Flask-Login) @@ -1528,7 +1528,7 @@ Test email settings by sending a test email. **Authentication:** Required -**Success Response (200 OK):** +**Success Response (501 Not Implemented):** ```json { "status": "not_implemented", @@ -1536,7 +1536,7 @@ Test email settings by sending a test email. } ``` -**Note:** This endpoint returns 501 Not Implemented. Full email functionality will be added in Phase 4. +**Note:** This endpoint returns 501 Not Implemented. Full email testing functionality will be added in a future phase. **Usage Example:** ```bash @@ -1570,13 +1570,11 @@ curl -X GET http://localhost:5000/api/settings/health ## Alerts API -Manage alert history and alert rules. Most functionality is planned for Phase 4. - -**Note:** The Alerts API endpoints are currently stub implementations returning placeholder data. Full alert functionality including email notifications and rule-based triggering will be implemented in Phase 4. +Manage alert history and alert rules with full support for filtering, acknowledgment, and statistics. ### List Alerts -List recent alerts with pagination and filtering. +List recent alerts with pagination and extensive filtering options. **Endpoint:** `GET /api/alerts` @@ -1586,27 +1584,111 @@ List recent alerts with pagination and filtering. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| -| `page` | integer | No | 1 | Page number | -| `per_page` | integer | No | 20 | Items per page | -| `alert_type` | string | No | - | Filter by alert type | +| `page` | integer | No | 1 | Page number (1-indexed) | +| `per_page` | integer | No | 20 | Items per page (1-100) | +| `alert_type` | string | No | - | Filter by alert type (unexpected_port, drift_detection, cert_expiry, weak_tls, ping_failed) | | `severity` | string | No | - | Filter by severity (info, warning, critical) | -| `start_date` | string | No | - | Filter alerts after this date | -| `end_date` | string | No | - | Filter alerts before this date | +| `acknowledged` | boolean | No | - | Filter by acknowledgment status (true/false) | +| `scan_id` | integer | No | - | Filter by specific scan ID | +| `start_date` | string | No | - | Filter alerts after this date (ISO format) | +| `end_date` | string | No | - | Filter alerts before this date (ISO format) | **Success Response (200 OK):** ```json { - "alerts": [], - "total": 0, + "alerts": [ + { + "id": 1, + "scan_id": 42, + "scan_title": "Production Network Scan", + "rule_id": 3, + "alert_type": "cert_expiry", + "severity": "warning", + "message": "Certificate for 192.168.1.10:443 expires in 15 days", + "ip_address": "192.168.1.10", + "port": 443, + "acknowledged": false, + "acknowledged_at": null, + "acknowledged_by": null, + "email_sent": true, + "email_sent_at": "2025-11-18T10:30:00Z", + "webhook_sent": false, + "webhook_sent_at": null, + "created_at": "2025-11-18T10:30:00Z" + } + ], + "total": 1, "page": 1, "per_page": 20, - "message": "Alerts list endpoint - to be implemented in Phase 4" + "pages": 1 +} +``` + +**Usage Examples:** +```bash +# List all alerts +curl -X GET http://localhost:5000/api/alerts \ + -b cookies.txt + +# List only critical unacknowledged alerts +curl -X GET "http://localhost:5000/api/alerts?severity=critical&acknowledged=false" \ + -b cookies.txt + +# List alerts for a specific scan +curl -X GET "http://localhost:5000/api/alerts?scan_id=42" \ + -b cookies.txt + +# List alerts from last week +START_DATE=$(date -d '7 days ago' -Iseconds) +curl -X GET "http://localhost:5000/api/alerts?start_date=$START_DATE" \ + -b cookies.txt +``` + +### Acknowledge Alert + +Mark an alert as acknowledged. + +**Endpoint:** `POST /api/alerts/{alert_id}/acknowledge` + +**Authentication:** Required + +**Path Parameters:** + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `alert_id` | integer | Yes | Alert ID to acknowledge | + +**Request Body (Optional):** +```json +{ + "acknowledged_by": "admin" +} +``` + +**Success Response (200 OK):** +```json +{ + "status": "success", + "message": "Alert 1 acknowledged", + "acknowledged_by": "admin" +} +``` + +**Error Responses:** + +*400 Bad Request* - Failed to acknowledge: +```json +{ + "status": "error", + "message": "Failed to acknowledge alert 1" } ``` **Usage Example:** ```bash -curl -X GET http://localhost:5000/api/alerts \ +curl -X POST http://localhost:5000/api/alerts/1/acknowledge \ + -H "Content-Type: application/json" \ + -d '{"acknowledged_by":"admin"}' \ -b cookies.txt ``` @@ -1621,8 +1703,25 @@ List all configured alert rules. **Success Response (200 OK):** ```json { - "rules": [], - "message": "Alert rules list endpoint - to be implemented in Phase 4" + "rules": [ + { + "id": 1, + "name": "Certificate Expiry Warning", + "rule_type": "cert_expiry", + "enabled": true, + "threshold": 30, + "email_enabled": true, + "webhook_enabled": false, + "severity": "warning", + "filter_conditions": { + "ip_pattern": "192.168.*" + }, + "config_file": "/app/configs/production.yaml", + "created_at": "2025-11-01T10:00:00Z", + "updated_at": "2025-11-15T08:30:00Z" + } + ], + "total": 1 } ``` @@ -1643,28 +1742,110 @@ Create a new alert rule. **Request Body:** ```json { + "name": "Certificate Expiry Warning", "rule_type": "cert_expiry", "threshold": 30, "enabled": true, - "email_enabled": false + "email_enabled": true, + "webhook_enabled": false, + "severity": "warning", + "filter_conditions": { + "ip_pattern": "192.168.*" + }, + "config_file": "/app/configs/production.yaml" } ``` -**Success Response (501 Not Implemented):** +**Request Body Fields:** + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | No | User-friendly rule name (defaults to "{rule_type} rule") | +| `rule_type` | string | Yes | Type of alert (unexpected_port, drift_detection, cert_expiry, weak_tls, ping_failed) | +| `threshold` | integer | No | Threshold value (e.g., days for cert expiry, percentage for drift) | +| `enabled` | boolean | No | Whether rule is active (default: true) | +| `email_enabled` | boolean | No | Send email for this rule (default: false) | +| `webhook_enabled` | boolean | No | Send webhook for this rule (default: false) | +| `severity` | string | No | Alert severity: critical, warning, info (default: warning) | +| `filter_conditions` | object | No | JSON object with filter conditions | +| `config_file` | string | No | Config file to apply rule to (null for all configs) | + +**Success Response (201 Created):** ```json { - "rule_id": null, - "status": "not_implemented", - "message": "Alert rule creation endpoint - to be implemented in Phase 4", - "data": {...} + "status": "success", + "message": "Alert rule created successfully", + "rule": { + "id": 1, + "name": "Certificate Expiry Warning", + "rule_type": "cert_expiry", + "enabled": true, + "threshold": 30, + "email_enabled": true, + "webhook_enabled": false, + "severity": "warning", + "filter_conditions": { + "ip_pattern": "192.168.*" + }, + "config_file": "/app/configs/production.yaml", + "created_at": "2025-11-18T10:00:00Z", + "updated_at": "2025-11-18T10:00:00Z" + } } ``` -**Usage Example:** +**Error Responses:** + +*400 Bad Request* - Missing or invalid fields: +```json +{ + "status": "error", + "message": "rule_type is required" +} +``` + +*400 Bad Request* - Invalid rule type: +```json +{ + "status": "error", + "message": "Invalid rule_type. Must be one of: unexpected_port, drift_detection, cert_expiry, weak_tls, ping_failed" +} +``` + +*400 Bad Request* - Invalid severity: +```json +{ + "status": "error", + "message": "Invalid severity. Must be one of: critical, warning, info" +} +``` + +**Usage Examples:** ```bash +# Create certificate expiry rule curl -X POST http://localhost:5000/api/alerts/rules \ -H "Content-Type: application/json" \ - -d '{"rule_type":"cert_expiry","threshold":30}' \ + -d '{ + "name": "Cert Expiry Warning", + "rule_type": "cert_expiry", + "threshold": 30, + "severity": "warning", + "email_enabled": true + }' \ + -b cookies.txt + +# Create drift detection rule for specific config +curl -X POST http://localhost:5000/api/alerts/rules \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Production Drift Alert", + "rule_type": "drift_detection", + "threshold": 10, + "severity": "critical", + "config_file": "/app/configs/production.yaml", + "email_enabled": true, + "webhook_enabled": true + }' \ -b cookies.txt ``` @@ -1685,33 +1866,74 @@ Update an existing alert rule. **Request Body:** ```json { + "name": "Updated Rule Name", "threshold": 60, "enabled": true, - "email_enabled": true + "email_enabled": true, + "severity": "critical" } ``` -**Success Response (501 Not Implemented):** +**Note:** All fields are optional. Only provided fields will be updated. + +**Success Response (200 OK):** ```json { - "rule_id": 1, - "status": "not_implemented", - "message": "Alert rule update endpoint - to be implemented in Phase 4", - "data": {...} + "status": "success", + "message": "Alert rule updated successfully", + "rule": { + "id": 1, + "name": "Updated Rule Name", + "rule_type": "cert_expiry", + "enabled": true, + "threshold": 60, + "email_enabled": true, + "webhook_enabled": false, + "severity": "critical", + "filter_conditions": null, + "config_file": "/app/configs/production.yaml", + "created_at": "2025-11-01T10:00:00Z", + "updated_at": "2025-11-18T10:00:00Z" + } +} +``` + +**Error Responses:** + +*404 Not Found* - Rule doesn't exist: +```json +{ + "status": "error", + "message": "Alert rule 1 not found" +} +``` + +*400 Bad Request* - Invalid severity: +```json +{ + "status": "error", + "message": "Invalid severity. Must be one of: critical, warning, info" } ``` **Usage Example:** ```bash +# Disable a rule curl -X PUT http://localhost:5000/api/alerts/rules/1 \ -H "Content-Type: application/json" \ - -d '{"threshold":60}' \ + -d '{"enabled":false}' \ + -b cookies.txt + +# Update threshold and enable email +curl -X PUT http://localhost:5000/api/alerts/rules/1 \ + -H "Content-Type: application/json" \ + -d '{"threshold":15,"email_enabled":true}' \ -b cookies.txt ``` ### Delete Alert Rule -Delete an alert rule. +Delete an alert rule. Associated alerts are also deleted via cascade. **Endpoint:** `DELETE /api/alerts/rules/{rule_id}` @@ -1723,12 +1945,21 @@ Delete an alert rule. |-----------|------|----------|-------------| | `rule_id` | integer | Yes | Alert rule ID | -**Success Response (501 Not Implemented):** +**Success Response (200 OK):** ```json { - "rule_id": 1, - "status": "not_implemented", - "message": "Alert rule deletion endpoint - to be implemented in Phase 4" + "status": "success", + "message": "Alert rule 1 deleted successfully" +} +``` + +**Error Responses:** + +*404 Not Found* - Rule doesn't exist: +```json +{ + "status": "error", + "message": "Alert rule 1 not found" } ``` @@ -1738,6 +1969,58 @@ curl -X DELETE http://localhost:5000/api/alerts/rules/1 \ -b cookies.txt ``` +### Get Alert Statistics + +Get alert statistics for a specified time period. + +**Endpoint:** `GET /api/alerts/stats` + +**Authentication:** Required + +**Query Parameters:** + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `days` | integer | No | 7 | Number of days to look back (1-365) | + +**Success Response (200 OK):** +```json +{ + "stats": { + "total_alerts": 42, + "unacknowledged_count": 5, + "alerts_by_severity": { + "critical": 3, + "warning": 15, + "info": 24 + }, + "alerts_by_type": { + "cert_expiry": 10, + "drift_detection": 8, + "unexpected_port": 12, + "weak_tls": 7, + "ping_failed": 5 + }, + "date_range": { + "start": "2025-11-11T10:00:00Z", + "end": "2025-11-18T10:00:00Z", + "days": 7 + } + } +} +``` + +**Usage Examples:** +```bash +# Get stats for last 7 days +curl -X GET http://localhost:5000/api/alerts/stats \ + -b cookies.txt + +# Get stats for last 30 days +curl -X GET "http://localhost:5000/api/alerts/stats?days=30" \ + -b cookies.txt +``` + ### Health Check Check API health status. @@ -1751,7 +2034,7 @@ Check API health status. { "status": "healthy", "api": "alerts", - "version": "1.0.0-phase1" + "version": "1.0.0-phase5" } ``` @@ -1976,36 +2259,34 @@ All inputs are validated: ## Versioning -**Current Version:** 4.0 (Phase 4) +**Current Version:** 5.0 (Phase 5) -API versioning will be implemented in Phase 5. For now, the API is considered unstable and may change between phases. +API versioning will be implemented in future phases. For now, the API is considered stable for Phase 5 features. **Recent Breaking Changes:** - Phase 2 → Phase 3: Added scan comparison endpoint, schedules API - Phase 3 → Phase 4: Added configs API, stats API, multiple settings endpoints +- Phase 4 → Phase 5: Full alerts API implementation with filtering, acknowledgment, and statistics **Upcoming Changes:** -- Phase 4 → Phase 5: Full alert implementation with email notifications -- Phase 5: API versioning with backward compatibility guarantees +- Phase 6+: API versioning with backward compatibility guarantees --- ## API Summary -### Implemented APIs (Phase 4) +### Implemented APIs (Phase 5) - **Authentication API** - Login, logout, setup - **Scans API** - Full CRUD, status polling, comparison - **Configs API** - File management, CIDR generation, YAML upload - **Schedules API** - CRUD operations, manual triggering, APScheduler integration - **Stats API** - Trends, summaries, historical data - **Settings API** - Application configuration, password management - -### Partially Implemented -- **Alerts API** - Stub endpoints (full implementation in Phase 4 continuation) +- **Alerts API** - Full implementation with filtering, acknowledgment, rules management, and statistics ### Endpoint Count -- Total endpoints: 50+ -- Authenticated endpoints: 45+ +- Total endpoints: 55+ +- Authenticated endpoints: 50+ - Public endpoints: 5 (login, setup, health checks) --- @@ -2018,6 +2299,6 @@ For issues, questions, or feature requests: --- -**Last Updated:** 2025-11-17 -**Phase:** 4 - Alerts & Email Notifications -**Next Update:** Phase 5 - API Versioning & Stability +**Last Updated:** 2025-11-18 +**Phase:** 5 - Alerts Management +**Next Update:** Phase 6 - Future Enhancements