sneakygeek/SneakyScan
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated API docs

Browse Source
This commit is contained in:
Phillip Tarrant
2025-11-18 13:23:06 -06:00
parent 131e1f5a61
commit 3c740268c4
1 changed files with 333 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

385
docs/API_REFERENCE.md
View File

@@ -1,6 +1,6 @@
# SneakyScanner Web API Reference # SneakyScanner Web API Reference
**Version:** 4.0 (Phase 4) **Version:** 5.0 (Phase 5)
**Base URL:** `http://localhost:5000` **Base URL:** `http://localhost:5000`
**Authentication:** Session-based (Flask-Login) **Authentication:** Session-based (Flask-Login)
@@ -1528,7 +1528,7 @@ Test email settings by sending a test email.
**Authentication:** Required **Authentication:** Required
**Success Response (200 OK):** **Success Response (501 Not Implemented):**
```json ```json
{ {
"status": "not_implemented", "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:** **Usage Example:**
```bash ```bash
@@ -1570,13 +1570,11 @@ curl -X GET http://localhost:5000/api/settings/health
## Alerts API ## Alerts API
Manage alert history and alert rules. Most functionality is planned for Phase 4. Manage alert history and alert rules with full support for filtering, acknowledgment, and statistics.
**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.
### List Alerts ### List Alerts
List recent alerts with pagination and filtering. List recent alerts with pagination and extensive filtering options.
**Endpoint:** `GET /api/alerts` **Endpoint:** `GET /api/alerts`
@@ -1586,27 +1584,111 @@ List recent alerts with pagination and filtering.
| Parameter | Type | Required | Default | Description | | Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------| |-----------|------|----------|---------|-------------|
| `page` | integer | No | 1 | Page number | | `page` | integer | No | 1 | Page number (1-indexed) |
| `per_page` | integer | No | 20 | Items per page | | `per_page` | integer | No | 20 | Items per page (1-100) |
| `alert_type` | string | No | - | Filter by alert type | | `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) | | `severity` | string | No | - | Filter by severity (info, warning, critical) |
| `start_date` | string | No | - | Filter alerts after this date | | `acknowledged` | boolean | No | - | Filter by acknowledgment status (true/false) |
| `end_date` | string | No | - | Filter alerts before this date | | `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):** **Success Response (200 OK):**
```json ```json
{ {
"alerts": [], "alerts": [
"total": 0, {
"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, "page": 1,
"per_page": 20, "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:** **Usage Example:**
```bash ```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 -b cookies.txt
``` ```
@@ -1621,8 +1703,25 @@ List all configured alert rules.
**Success Response (200 OK):** **Success Response (200 OK):**
```json ```json
{ {
"rules": [], "rules": [
"message": "Alert rules list endpoint - to be implemented in Phase 4" {
"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:** **Request Body:**
```json ```json
{ {
"name": "Certificate Expiry Warning",
"rule_type": "cert_expiry", "rule_type": "cert_expiry",
"threshold": 30, "threshold": 30,
"enabled": true, "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 ```json
{ {
"rule_id": null, "status": "success",
"status": "not_implemented", "message": "Alert rule created successfully",
"message": "Alert rule creation endpoint - to be implemented in Phase 4", "rule": {
"data": {...} "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 ```bash
# Create certificate expiry rule
curl -X POST http://localhost:5000/api/alerts/rules \ curl -X POST http://localhost:5000/api/alerts/rules \
-H "Content-Type: application/json" \ -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 -b cookies.txt
``` ```
@@ -1685,33 +1866,74 @@ Update an existing alert rule.
**Request Body:** **Request Body:**
```json ```json
{ {
"name": "Updated Rule Name",
"threshold": 60, "threshold": 60,
"enabled": true, "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 ```json
{ {
"rule_id": 1, "status": "success",
"status": "not_implemented", "message": "Alert rule updated successfully",
"message": "Alert rule update endpoint - to be implemented in Phase 4", "rule": {
"data": {...} "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:** **Usage Example:**
```bash ```bash
# Disable a rule
curl -X PUT http://localhost:5000/api/alerts/rules/1 \ curl -X PUT http://localhost:5000/api/alerts/rules/1 \
-H "Content-Type: application/json" \ -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 -b cookies.txt
``` ```
### Delete Alert Rule ### 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}` **Endpoint:** `DELETE /api/alerts/rules/{rule_id}`
@@ -1723,12 +1945,21 @@ Delete an alert rule.
|-----------|------|----------|-------------| |-----------|------|----------|-------------|
| `rule_id` | integer | Yes | Alert rule ID | | `rule_id` | integer | Yes | Alert rule ID |
**Success Response (501 Not Implemented):** **Success Response (200 OK):**
```json ```json
{ {
"rule_id": 1, "status": "success",
"status": "not_implemented", "message": "Alert rule 1 deleted successfully"
"message": "Alert rule deletion endpoint - to be implemented in Phase 4" }
```
**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 -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 ### Health Check
Check API health status. Check API health status.
@@ -1751,7 +2034,7 @@ Check API health status.
{ {
"status": "healthy", "status": "healthy",
"api": "alerts", "api": "alerts",
"version": "1.0.0-phase1" "version": "1.0.0-phase5"
} }
``` ```
@@ -1976,36 +2259,34 @@ All inputs are validated:
## Versioning ## 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:** **Recent Breaking Changes:**
- Phase 2 → Phase 3: Added scan comparison endpoint, schedules API - Phase 2 → Phase 3: Added scan comparison endpoint, schedules API
- Phase 3 → Phase 4: Added configs API, stats API, multiple settings endpoints - 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:** **Upcoming Changes:**
- Phase 4 → Phase 5: Full alert implementation with email notifications - Phase 6+: API versioning with backward compatibility guarantees
- Phase 5: API versioning with backward compatibility guarantees
--- ---
## API Summary ## API Summary
### Implemented APIs (Phase 4) ### Implemented APIs (Phase 5)
- **Authentication API** - Login, logout, setup - **Authentication API** - Login, logout, setup
- **Scans API** - Full CRUD, status polling, comparison - **Scans API** - Full CRUD, status polling, comparison
- **Configs API** - File management, CIDR generation, YAML upload - **Configs API** - File management, CIDR generation, YAML upload
- **Schedules API** - CRUD operations, manual triggering, APScheduler integration - **Schedules API** - CRUD operations, manual triggering, APScheduler integration
- **Stats API** - Trends, summaries, historical data - **Stats API** - Trends, summaries, historical data
- **Settings API** - Application configuration, password management - **Settings API** - Application configuration, password management
- **Alerts API** - Full implementation with filtering, acknowledgment, rules management, and statistics
### Partially Implemented
- **Alerts API** - Stub endpoints (full implementation in Phase 4 continuation)
### Endpoint Count ### Endpoint Count
- Total endpoints: 50+ - Total endpoints: 55+
- Authenticated endpoints: 45+ - Authenticated endpoints: 50+
- Public endpoints: 5 (login, setup, health checks) - Public endpoints: 5 (login, setup, health checks)
--- ---
@@ -2018,6 +2299,6 @@ For issues, questions, or feature requests:
--- ---
**Last Updated:** 2025-11-17 **Last Updated:** 2025-11-18
**Phase:** 4 - Alerts & Email Notifications **Phase:** 5 - Alerts Management
**Next Update:** Phase 5 - API Versioning & Stability **Next Update:** Phase 6 - Future Enhancements