Findings API

The Findings API provides complete CRUD operations for managing security findings (vulnerabilities) within projects. You can create findings from scratch, use templates, update remediation status, and perform bulk operations.

Endpoints

List All Findings

Get findings across all projects with filtering.

GET /api/v1/findings

Query Parameters:

search (string) - Search findings by title, description, or POC
status (string) - Filter by status: draft, in-progress, done
impact (string) - Filter by severity: informational, low, medium, high, critical
project_id (integer) - Filter by project ID

Response:

{
  "success": true,
  "data": [
    {
      "id": 456,
      "uuid": "finding-uuid-here",
      "title": "SQL Injection in Login Form",
      "description": "The login form is vulnerable to SQL injection attacks",
      "impact": "high",
      "probability": "medium",
      "cvss": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:N",
      "cvss_score": 8.1,
      "status": "draft",
      "remediation_stage": null,
      "order": 1,
      "project": {
        "id": 123,
        "uuid": "project-uuid",
        "name": "E-commerce Assessment"
      },
      "user": {
        "id": 5,
        "name": "John Doe",
        "email": "john@company.com"
      },
      "vulnerability": {
        "id": 15,
        "title": "SQL Injection Template"
      },
      "risk": "High",
      "can_update": true,
      "can_delete": true,
      "created_at": "2024-03-15T10:30:00Z",
      "updated_at": "2024-03-15T11:45:00Z"
    }
  ],
  "total": 1
}

Get Project Findings

Get findings for a specific project.

GET /api/v1/projects/{project_uuid}/findings

Query Parameters:

search (string) - Search findings
status (string) - Filter by status
impact (string) - Filter by severity

Response:

{
  "success": true,
  "data": [
    // Array of findings for the project
  ],
  "stats": {
    "total": 15,
    "by_status": {
      "draft": 8,
      "in-progress": 5,
      "done": 2
    },
    "by_impact": {
      "critical": 2,
      "high": 5,
      "medium": 6,
      "low": 2,
      "informational": 0
    },
    "by_remediation_stage": {
      "not_started": 10,
      "requested": 3,
      "in_progress": 1,
      "completed": 1
    }
  },
  "total": 15
}

Get Finding Details

Get detailed information about a specific finding.

GET /api/v1/findings/{finding_uuid}

Response:

{
  "success": true,
  "data": {
    "id": 456,
    "uuid": "finding-uuid-here",
    "title": "SQL Injection in Login Form",
    "description": "The application's login form does not properly sanitize user input, allowing attackers to inject malicious SQL code.",
    "impact": "high",
    "probability": "medium",
    "cvss": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:N",
    "cvss_score": 8.1,
    "status": "draft",
    "remediation_stage": null,
    "order": 1,
    "poc": "1. Navigate to /login\n2. Enter: admin' OR 1=1 --\n3. Observe successful authentication bypass",
    "risks": "- Unauthorized access to user accounts\n- Data breach potential\n- Complete system compromise",
    "remediation": "1. Implement parameterized queries\n2. Use prepared statements\n3. Implement input validation",
    "http_excerpts": "POST /login HTTP/1.1\nContent-Type: application/json\n\n{\"username\":\"admin' OR 1=1 --\",\"password\":\"anything\"}",
    "extra_fields": {
      "cwe_id": "CWE-89",
      "owasp_category": "A03:2021 – Injection"
    },
    "template_id": 15,
    "vulnerability_id": null,
    "project_type_id": 1,
    "affected_hosts": [
      {
        "id": 1,
        "endpoint": "https://example.com/login",
        "port": 443,
        "protocol": "HTTPS",
        "description": "Main login endpoint"
      }
    ],
    "categories": [
      {
        "id": 1,
        "name": "Injection Attacks"
      },
      {
        "id": 5,
        "name": "Authentication Issues"
      }
    ]
  }
}

Create Finding

Create a new finding in a project.

POST /api/v1/projects/{project_uuid}/findings

Request Body:

{
  "title": "Cross-Site Scripting (XSS) Vulnerability",
  "description": "The search parameter reflects user input without proper encoding",
  "impact": "medium",
  "probability": "high",
  "cvss": "CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:C/C:L/I:L/A:N",
  "cvss_score": 6.1,
  "poc": "1. Go to /search?q=<script>alert(1)</script>\n2. Observe script execution",
  "risks": "- Session hijacking\n- Credential theft\n- Malicious content injection",
  "remediation": "- Implement proper output encoding\n- Use Content Security Policy\n- Validate all user input",
  "http_excerpts": "GET /search?q=<script>alert(document.cookie)</script>",
  "status": "draft",
  "affected_hosts": [
    {
      "endpoint": "https://example.com/search",
      "port": 443,
      "protocol": "HTTPS",
      "description": "Search functionality"
    }
  ],
  "categories": [2, 3],
  "extra_fields": {
    "cwe_id": "CWE-79",
    "owasp_category": "A03:2021 – Injection"
  }
}

Response:

{
  "success": true,
  "message": "Finding created successfully.",
  "data": {
    "id": 457,
    "uuid": "new-finding-uuid",
    "title": "Cross-Site Scripting (XSS) Vulnerability",
    // ... full finding details
  }
}

Create Finding from Template

Create a finding based on an existing template.

POST /api/v1/projects/{project_uuid}/findings/template

Request Body:

{
  "template_id": 15,
  "title": "SQL Injection in Contact Form",
  "affected_hosts": [
    {
      "endpoint": "https://example.com/contact",
      "port": 443,
      "protocol": "HTTPS",
      "description": "Contact form endpoint"
    }
  ],
  "extra_fields": {
    "specific_parameter": "email field"
  }
}

Update Finding

Update an existing finding.

PUT /api/v1/findings/{finding_uuid}
PATCH /api/v1/findings/{finding_uuid}

Request Body (partial update):

{
  "status": "done",
  "remediation": "Updated remediation steps after client feedback",
  "remediation_stage": "completed"
}

Update Remediation Status

Specifically update the remediation status of a finding.

PATCH /api/v1/findings/{finding_uuid}/remediation

Request Body:

{
  "remediation_stage": "in_progress",
  "remediation": "Client has started implementing the fix",
  "status": "in-progress"
}

Remediation Stages:

null - Not remediated
requested - Remediation requested
in_progress - Remediation in progress
completed - Fully remediated
partial - Partially remediated

Delete Finding

Delete a finding.

DELETE /api/v1/findings/{finding_uuid}

Batch Delete Findings

Delete multiple findings at once.

DELETE /api/v1/findings?ids=uuid1,uuid2,uuid3

Response:

{
  "success": true,
  "message": "3 findings deleted successfully.",
  "deleted_count": 3
}

Reorder Findings

Change the order of findings within a project.

PATCH /api/v1/projects/{project_uuid}/findings/order

Request Body:

{
  "findings": [
    {
      "uuid": "finding-uuid-1",
      "order": 1
    },
    {
      "uuid": "finding-uuid-2",
      "order": 2
    },
    {
      "uuid": "finding-uuid-3",
      "order": 3
    }
  ]
}

Examples

Create a Finding

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Broken Authentication",
    "description": "Weak password policy allows brute force attacks",
    "impact": "high",
    "probability": "medium",
    "poc": "1. Use Hydra to brute force login\n2. Successfully crack weak passwords",
    "affected_hosts": [
      {
        "endpoint": "https://example.com/admin",
        "port": 443
      }
    ]
  }' \
  https://your-instance.pentestpad.com/api/v1/projects/project-uuid/findings

Search Findings

curl -H "Authorization: Bearer your_api_key" \
     "https://your-instance.pentestpad.com/api/v1/findings?search=injection&impact=high"

Update Finding Status

curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "done", "remediation_stage": "completed"}' \
  https://your-instance.pentestpad.com/api/v1/findings/finding-uuid/remediation

Field Validation

Required Fields

title - Finding title (max 255 characters)
impact - Must be: informational, low, medium, high, critical
probability - Must be: informational, low, medium, high, critical

Optional Fields

description - Text description
poc - Proof of concept steps
risks - Risk assessment
remediation - Remediation guidance
cvss - CVSS vector string
cvss_score - Numeric score (0-10)
http_excerpts - HTTP request/response examples
status - Must be: draft, in-progress, done
extra_fields - JSON object for custom fields
affected_hosts - Array of affected endpoints
categories - Array of category IDs

Risk Calculation

PentestPad automatically calculates risk levels based on impact and probability using a standard matrix:

Impact/Probability	Informational	Low	Medium	High	Critical
Informational	Informational	Informational	Low	Medium	Medium
Low	Informational	Low	Low	Medium	Medium
Medium	Low	Low	Medium	High	High
High	Medium	Medium	High	Critical	Critical
Critical	Medium	Medium	High	Critical	Critical

Findings API

Endpoints

List All Findings

Get Project Findings

Get Finding Details

Create Finding

Create Finding from Template

Update Finding

Update Remediation Status

Delete Finding

Batch Delete Findings

Reorder Findings

Examples

Create a Finding

Search Findings

Update Finding Status

Field Validation

Required Fields

Optional Fields

Risk Calculation

Permissions