> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/usestrix/strix/llms.txt
> Use this file to discover all available pages before exploring further.

# Vulnerability Format

> Detailed reference for Strix vulnerability report structure and fields

Strix generates structured vulnerability reports following security industry standards. This page documents the complete vulnerability report format.

## Report Structure

Each vulnerability report contains comprehensive information organized into these sections:

* **Identification** - Unique identifiers and metadata
* **Classification** - Severity, CVSS scoring, CVE/CWE mappings
* **Description** - What the vulnerability is and why it matters
* **Technical Details** - How the vulnerability works
* **Proof of Concept** - Reproducible exploit demonstration
* **Code Analysis** - Source code locations (for white-box testing)
* **Remediation** - How to fix the vulnerability

## Field Reference

### Identification Fields

<ParamField path="id" type="string" required>
  Unique identifier for the vulnerability.

  Format: `vuln-<8-char-hex>`

  Example: `vuln-a3f8b2e1`

  This ID is stable and can be used to track the vulnerability across systems.
</ParamField>

<ParamField path="timestamp" type="string" required>
  ISO 8601 timestamp when the vulnerability was discovered.

  Format: `YYYY-MM-DDTHH:MM:SSZ`

  Example: `2026-03-01T12:34:56Z`

  Always in UTC timezone.
</ParamField>

<ParamField path="title" type="string" required>
  Brief, descriptive title of the vulnerability.

  Guidelines:

  * Be specific and actionable
  * Include vulnerability type
  * Mention affected component
  * Keep under 100 characters

  Examples:

  * `SQL Injection in Search Endpoint`
  * `Authentication Bypass via JWT Manipulation`
  * `Sensitive Data Exposure in API Response`
</ParamField>

### Classification Fields

<ParamField path="severity" type="string" required>
  Severity classification based on CVSS score.

  Possible values:

  * `critical` - CVSS 9.0-10.0
  * `high` - CVSS 7.0-8.9
  * `medium` - CVSS 4.0-6.9
  * `low` - CVSS 0.1-3.9
  * `info` - CVSS 0.0

  Automatically calculated from CVSS breakdown.
</ParamField>

<ParamField path="cvss" type="number" required>
  CVSS v3.1 base score.

  Range: `0.0` to `10.0`

  Precision: One decimal place

  Examples: `9.8`, `7.5`, `4.3`

  Automatically calculated from CVSS breakdown using the official CVSS v3.1 algorithm.
</ParamField>

<ParamField path="cvss_breakdown" type="object" required>
  Complete CVSS v3.1 metric breakdown.

  **Attack Vector (AV)**

  * `N` - Network (remotely exploitable)
  * `A` - Adjacent Network (local network required)
  * `L` - Local (local access required)
  * `P` - Physical (physical access required)

  **Attack Complexity (AC)**

  * `L` - Low (no special conditions)
  * `H` - High (requires specific conditions)

  **Privileges Required (PR)**

  * `N` - None (unauthenticated)
  * `L` - Low (basic user account)
  * `H` - High (admin/privileged account)

  **User Interaction (UI)**

  * `N` - None (no user action needed)
  * `R` - Required (victim must take action)

  **Scope (S)**

  * `U` - Unchanged (impact limited to vulnerable component)
  * `C` - Changed (impact extends beyond vulnerable component)

  **Confidentiality (C)**

  * `N` - None (no information disclosure)
  * `L` - Low (limited information disclosure)
  * `H` - High (total information disclosure)

  **Integrity (I)**

  * `N` - None (no data modification)
  * `L` - Low (limited data modification)
  * `H` - High (complete data manipulation)

  **Availability (A)**

  * `N` - None (no service disruption)
  * `L` - Low (degraded performance)
  * `H` - High (complete denial of service)

  Example:

  ```json theme={null}
  {
    "attack_vector": "N",
    "attack_complexity": "L",
    "privileges_required": "N",
    "user_interaction": "N",
    "scope": "U",
    "confidentiality": "H",
    "integrity": "H",
    "availability": "H"
  }
  ```

  CVSS Vector String: `CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H`
</ParamField>

<ParamField path="cve" type="string">
  CVE (Common Vulnerabilities and Exposures) identifier if applicable.

  Format: `CVE-YYYY-NNNNN`

  Example: `CVE-2024-12345`

  Only included when the vulnerability corresponds to a known CVE.
</ParamField>

<ParamField path="cwe" type="string">
  CWE (Common Weakness Enumeration) identifier.

  Format: `CWE-NNN`

  Examples:

  * `CWE-89` - SQL Injection
  * `CWE-79` - Cross-Site Scripting (XSS)
  * `CWE-287` - Improper Authentication
  * `CWE-352` - Cross-Site Request Forgery (CSRF)
  * `CWE-22` - Path Traversal

  See [cwe.mitre.org](https://cwe.mitre.org) for complete list.
</ParamField>

### Target Fields

<ParamField path="target" type="string" required>
  The target where the vulnerability was found.

  Examples:

  * `https://example.com`
  * `https://github.com/user/repo`
  * `./my-project`
  * `example.com`
  * `192.168.1.42`
</ParamField>

<ParamField path="endpoint" type="string">
  Specific endpoint, path, or resource affected.

  Examples:

  * `/api/search`
  * `/auth/login`
  * `/users/{id}/profile`
  * `ws://example.com/chat`

  For web applications, this is typically a URL path. For code analysis, it may be a module or function name.
</ParamField>

<ParamField path="method" type="string">
  HTTP method or operation type.

  Examples:

  * `GET`
  * `POST`
  * `PUT`
  * `DELETE`
  * `PATCH`
  * `WebSocket`
  * `GraphQL Query`
</ParamField>

### Description Fields

<ParamField path="description" type="string" required>
  Detailed description of the vulnerability.

  Should explain:

  * What the vulnerability is
  * Where it exists
  * Under what conditions it can be exploited
  * Basic technical mechanism

  Example:

  ```
  The search parameter in the /api/search endpoint is vulnerable to SQL 
  injection. User-supplied input is concatenated directly into SQL queries 
  without sanitization or parameterization, allowing attackers to execute 
  arbitrary SQL commands against the backend database.
  ```

  Typically 2-4 sentences providing clear context.
</ParamField>

<ParamField path="impact" type="string" required>
  Potential impact and consequences of exploitation.

  Should explain:

  * What an attacker could achieve
  * Data or systems at risk
  * Business consequences
  * Compliance implications

  Example:

  ```
  Successful exploitation allows attackers to:
  - Extract all database contents including user credentials
  - Modify or delete critical data
  - Bypass authentication and authorization controls
  - Potentially gain operating system access via database functions

  This could result in complete system compromise, data breach of sensitive 
  customer information, and violation of GDPR/PCI-DSS compliance requirements.
  ```

  Typically 3-5 bullet points or paragraphs.
</ParamField>

<ParamField path="technical_analysis" type="string" required>
  In-depth technical analysis of the vulnerability.

  Should include:

  * How the vulnerability works at a technical level
  * Root cause analysis
  * Attack vector details
  * Any preconditions or limitations

  Example:

  ```
  The application constructs SQL queries using Python f-strings:

  query = f"SELECT * FROM users WHERE name = '{user_input}'"

  When user_input contains SQL metacharacters, they are interpreted as SQL 
  syntax rather than literal data. An attacker can close the quoted string 
  and append additional SQL commands:

  user_input = "' OR '1'='1" results in:
  query = "SELECT * FROM users WHERE name = '' OR '1'='1'"

  This returns all user records. More sophisticated payloads can extract 
  data from other tables, invoke stored procedures, or read files.

  The vulnerability exists because:
  1. Input is not validated or sanitized
  2. Parameterized queries are not used
  3. Database permissions are overly broad
  ```

  Typically several paragraphs with technical details.
</ParamField>

### Proof of Concept Fields

<ParamField path="poc_description" type="string" required>
  Step-by-step description of how to reproduce the vulnerability.

  Should include:

  * Prerequisites and setup
  * Exact steps to reproduce
  * Expected vs actual results
  * How to verify exploitation succeeded

  Example:

  ```
  To reproduce this vulnerability:

  1. Navigate to https://example.com/search
  2. In the search field, enter: ' OR '1'='1
  3. Submit the search form
  4. Observe that all user records are returned instead of filtered results

  Alternatively, using curl:

  curl "https://example.com/api/search?q=' OR '1'='1"

  The response will contain all database records, confirming the SQL 
  injection vulnerability.

  For more advanced exploitation, use the proof-of-concept script below.
  ```

  Typically 3-6 numbered steps.
</ParamField>

<ParamField path="poc_script_code" type="string" required>
  Actual exploit code or payload demonstrating the vulnerability.

  Requirements:

  * Must be functional, working code
  * Include all necessary imports and dependencies
  * Add comments explaining key steps
  * Use realistic but safe payloads
  * Include error handling

  Example:

  ```python theme={null}
  import requests

  # Target URL
  target = "https://example.com/api/search"

  # SQL injection payload to extract database version
  payload = "' UNION SELECT NULL, version(), NULL-- "

  # Send malicious request
  response = requests.get(
      target,
      params={"q": payload},
      headers={"User-Agent": "Mozilla/5.0"}
  )

  # Check if successful
  if response.status_code == 200:
      print("[+] SQL Injection successful")
      print(f"[+] Database version: {response.json()}")
  else:
      print("[-] Exploitation failed")

  # Extract user credentials
  payload = "' UNION SELECT username, password, NULL FROM users-- "
  response = requests.get(target, params={"q": payload})

  if response.status_code == 200:
      users = response.json()
      print(f"[+] Extracted {len(users)} user records")
      for user in users:
          print(f"  {user['username']}: {user['password']}")
  ```

  Must include working exploit code. This is a required field.
</ParamField>

### Code Location Fields

<ParamField path="code_locations" type="array">
  Array of source code locations related to the vulnerability.

  Only included for white-box testing when source code is available.

  Each location object contains:

  **file** (string, required)

  * Relative path to the file
  * Must be relative, not absolute
  * Must not contain `..` path traversal
  * Example: `src/api/search.py`

  **start\_line** (integer, required)

  * Starting line number (1-indexed)
  * Must be positive integer
  * Example: `42`

  **end\_line** (integer, required)

  * Ending line number (1-indexed)
  * Must be >= start\_line
  * Example: `45`

  **snippet** (string, optional)

  * Code snippet showing the vulnerable code
  * Preserves original formatting
  * Example:
    ```python theme={null}
    query = f"SELECT * FROM users WHERE name = '{user_input}'"
    results = db.execute(query)
    ```

  **label** (string, optional)

  * Description of this code location
  * Example: `Vulnerable SQL query construction`

  **fix\_before** (string, optional)

  * Original vulnerable code
  * Used for showing diffs

  **fix\_after** (string, optional)

  * Suggested fixed code
  * Used for showing diffs

  Example:

  ```json theme={null}
  [
    {
      "file": "src/api/search.py",
      "start_line": 42,
      "end_line": 45,
      "snippet": "query = f\"SELECT * FROM users WHERE name = '{user_input}'\"\nresults = db.execute(query)",
      "label": "Vulnerable SQL query construction",
      "fix_before": "query = f\"SELECT * FROM users WHERE name = '{user_input}'\"",
      "fix_after": "query = \"SELECT * FROM users WHERE name = ?\"\nresults = db.execute(query, (user_input,))"
    },
    {
      "file": "src/api/search.py",
      "start_line": 15,
      "end_line": 18,
      "label": "Missing input validation"
    }
  ]
  ```
</ParamField>

### Remediation Fields

<ParamField path="remediation_steps" type="string" required>
  Step-by-step instructions to fix the vulnerability.

  Should include:

  * Immediate mitigation steps
  * Long-term fixes
  * Code changes with examples
  * Configuration changes
  * Testing procedures
  * Prevention measures

  Example:

  ```
  Immediate remediation:

  1. Use parameterized queries instead of string concatenation:

     Before:
     query = f"SELECT * FROM users WHERE name = '{user_input}'"
     
     After:
     query = "SELECT * FROM users WHERE name = ?"
     results = db.execute(query, (user_input,))

  2. Implement input validation:
     - Whitelist allowed characters
     - Enforce maximum length limits
     - Reject SQL metacharacters

  3. Apply principle of least privilege:
     - Use read-only database account for queries
     - Revoke unnecessary permissions
     - Use separate accounts for different operations

  Long-term improvements:

  4. Enable query logging and monitoring
  5. Implement Web Application Firewall (WAF) rules
  6. Conduct regular security code reviews
  7. Use static analysis tools in CI/CD pipeline
  8. Provide security training for developers

  Testing:

  After implementing fixes, verify:
  - Original exploit no longer works
  - Legitimate queries still function correctly
  - Error handling doesn't leak information
  - Logs capture attempted attacks
  ```

  Typically 5-10 numbered steps with code examples.
</ParamField>

## Complete Example

Here's a complete vulnerability report showing all fields:

```json theme={null}
{
  "id": "vuln-a3f8b2e1",
  "timestamp": "2026-03-01T12:34:56Z",
  "title": "SQL Injection in Search Endpoint",
  "severity": "critical",
  "cvss": 9.8,
  "cvss_breakdown": {
    "attack_vector": "N",
    "attack_complexity": "L",
    "privileges_required": "N",
    "user_interaction": "N",
    "scope": "U",
    "confidentiality": "H",
    "integrity": "H",
    "availability": "H"
  },
  "target": "https://example.com",
  "endpoint": "/api/search",
  "method": "GET",
  "cve": "CVE-2024-12345",
  "cwe": "CWE-89",
  "description": "The search parameter is vulnerable to SQL injection, allowing attackers to execute arbitrary SQL commands against the database.",
  "impact": "Complete database compromise including extraction of user credentials, sensitive data, and potential for data modification or deletion.",
  "technical_analysis": "The application concatenates user input directly into SQL queries without proper sanitization or parameterization...",
  "poc_description": "Send a GET request to /api/search with a malicious query parameter...",
  "poc_script_code": "import requests\n\npayload = \"' OR '1'='1\"\nresponse = requests.get(...)",
  "remediation_steps": "1. Use parameterized queries\n2. Implement input validation...",
  "code_locations": [
    {
      "file": "src/api/search.py",
      "start_line": 42,
      "end_line": 45,
      "snippet": "query = f\"SELECT * FROM users WHERE name = '{user_input}'\"\nresults = db.execute(query)",
      "label": "Vulnerable SQL query construction",
      "fix_before": "query = f\"SELECT * FROM users WHERE name = '{user_input}'\"",
      "fix_after": "query = \"SELECT * FROM users WHERE name = ?\"\nresults = db.execute(query, (user_input,))"
    }
  ]
}
```

## Validation Rules

Strix validates vulnerability reports before creating them:

### Required Field Validation

All required fields must be present and non-empty:

* title
* description
* impact
* target
* technical\_analysis
* poc\_description
* poc\_script\_code (must contain actual exploit code)
* remediation\_steps
* cvss\_breakdown

### CVSS Validation

CVSS metrics must use valid values:

* attack\_vector: N, A, L, or P
* attack\_complexity: L or H
* privileges\_required: N, L, or H
* user\_interaction: N or R
* scope: U or C
* confidentiality: N, L, or H
* integrity: N, L, or H
* availability: N, L, or H

### CVE/CWE Validation

* CVE format: `CVE-YYYY-NNNNN` (e.g., `CVE-2024-12345`)
* CWE format: `CWE-NNN` (e.g., `CWE-89`)

### Code Location Validation

When code\_locations is provided:

* file path must be relative (not absolute)
* file path must not contain `..`
* start\_line must be positive integer
* end\_line must be positive integer >= start\_line

## Duplicate Detection

Strix automatically detects and prevents duplicate vulnerability reports:

```json theme={null}
{
  "success": false,
  "message": "Potential duplicate of 'SQL Injection in Search' (id=vuln-xyz12345...). Do not re-report the same vulnerability.",
  "duplicate_of": "vuln-xyz12345abc",
  "duplicate_title": "SQL Injection in Search",
  "confidence": 0.92,
  "reason": "Same endpoint and vulnerability type"
}
```

Duplicates are detected using:

* Same target + endpoint + vulnerability type
* Similar title and description (via LLM similarity)
* Same CVE or CWE

## See Also

* [Reports](/cli/reports) - Report file formats
* [Examples](/cli/examples) - Usage examples
* [CVSS v3.1 Specification](https://www.first.org/cvss/v3.1/specification-document)
* [CWE List](https://cwe.mitre.org/data/index.html)