> ## Documentation Index
> Fetch the complete documentation index at: https://qodex.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Security scenarios
> Security scenarios are saved attack checks where pass means the app blocked the attack and fail means the app is vulnerable.
# Security scenarios
Security scenarios are repeatable tests for attack behavior. They look like normal API scenarios, but their meaning is different: pass means the app blocked the attack, and fail means the app may be vulnerable.
This lets security checks live beside functional tests without losing the evidence and severity model needed for security work.
## Functional scenario vs security scenario
A functional scenario checks that the app does what it should do. A security scenario checks that the app refuses what it should not allow.
| Field | Functional scenario | Security scenario |
| --------------- | ---------------------------------- | ------------------------------------------------- |
| Example goal | Create a user with a valid payload | Prevent a regular user from setting `role: admin` |
| Expected result | The happy path succeeds | The attack is blocked or safely ignored |
| Pass means | The feature works | The defense works |
| Fail means | The feature is broken | The app may be vulnerable |
| Finding on fail | Functional bug | Security finding with evidence and OWASP category |
This difference is important. A failing security scenario is not something Qodex should "fix" by changing the expected status to `200`. The failure is the signal.
## How Qodex authors them
Security scenarios are created by the `security` and `pentest` skills.
* **security** creates methodical OWASP-aligned checks and regression scenarios.
* **pentest** goes deeper on a focused surface, chains attack vectors, and proves impact when possible.
The agent follows the same basic flow:
1. Reads the target surface, imported endpoints, auth profiles, memory, and environment constraints.
2. Chooses relevant probes such as BOLA, IDOR, auth bypass, injection, SSRF, or rate-limit checks.
3. Saves each check as a scenario with the secure result as the expected result.
4. Auto-verifies the scenario on save.
5. Opens a finding if verification shows the attack succeeded.
## Authoring from chat
Describe the surface and the risk you care about:
```text theme={null}
Run BOLA tests against /api/v1/orders. Cover GET, PUT, and DELETE.
Use the admin and viewer auth profiles.
```
```text theme={null}
Pentest the login flow. Focus on JWT manipulation, rate limiting,
default credentials, and password reset token reuse.
```
You can also constrain the run:
* Endpoint scope: "Only `/api/v1/orders/*`."
* Role scope: "Run as viewer against admin endpoints."
* Attack scope: "Skip rate limiting because it already ran today."
* Environment scope: "Use staging, not production."
## How severity is chosen
Qodex maps findings to severity based on impact:
| Severity | Examples |
| ---------- | -------------------------------------------------------------------------------------------------- |
| `critical` | Auth bypass to admin, SQL injection with data access, SSRF to cloud metadata, exposed credentials. |
| `high` | IDOR with data exposure, privilege escalation, stored XSS, broken access control. |
| `medium` | Reflected XSS, missing rate limiting, internal information disclosure. |
| `low` | Missing headers, verbose errors, weak cookie flags on low-impact pages. |
| `info` | Technology disclosure, deprecated versions, attack surface notes. |
Every finding includes request and response evidence, reproduction steps, suggested remediation, and the OWASP category when applicable.
## Environment constraints
Before creating or running security scenarios, Qodex reads the active environment. Constraints decide what the agent is allowed to attempt:
* `read_only: true` blocks write verbs such as POST, PUT, PATCH, and DELETE.
* `allow_destructive_tests: false` blocks destructive payloads even when the HTTP verb is allowed.
* `max_requests_per_second` limits brute-force, burst, and rate-limit probes.
See [Sensitive endpoints](/security-testing-sensitive-endpoints) for examples of safe production and staging settings.
## Related
Learn the rule that protects security assertions.
See which probes Qodex runs for each category.
Understand how environment flags scope active tests.
Review the scenario model shared with API testing.
## On the roadmap
A planned `vulnerability-tests` skill will add CVE scanning, dependency checks, configuration audits, secret scanning, and code-pattern analysis alongside the existing security and pentest skills.