updated API docs

2025-11-18 13:23:06 -06:00
parent 131e1f5a61
commit 3c740268c4
1 changed files with 333 additions and 52 deletions
--- 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