> For the complete documentation index, see [llms.txt](https://support.attackforge.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.attackforge.com/app/getting-started/creating-vulnerabilities.md).
# Creating Vulnerabilities
## Overview
Vulnerabilities are the findings from testing. Each one records what was found, where, how serious it is, how to reproduce it and how to fix it. Every vulnerability is created on a project and linked to the asset or assets in that project's scope that it affects.
## Why it matters how vulnerabilities are created
A vulnerability is often the only part of a test that developers, asset owners and executives read, so its quality matters.
* **Consistent, client-ready writing.** Starting from a writeup library means descriptions, attack scenarios and remediation advice are written once, reviewed, and reused, rather than rewritten under deadline pressure.
* **Accurate prioritisation.** Scoring sets the priority that drives SLAs, dashboards and the order fixes happen in.
* **Faster remediation.** Vulnerabilities are visible to the project team as soon as they're created, so fixes can start before the report is issued, which reduces time to remediate.
* **Less noise from scanners.** Imports can group thousands of scanner results into a manageable set of unique findings, without losing any asset detail.
* **Traceability.** Each vulnerability is linked to its assets and the test cases it failed, so you can see where it came from and track it through to closure.
## Who benefits
| Who | How |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Testers** | Reuse proven writeups, score consistently, import tool output instead of retyping it, and attach evidence once |
| **QA reviewers** | Review fewer, better-structured findings, using Pending visibility as a draft stage |
| **Developers and asset owners** | Clear steps to reproduce, evidence, affected components and remediation advice, available as soon as each finding is released |
| **Security and delivery managers** | Consistent priorities and data that feed SLAs, dashboards, analytics and reports |
## Seven ways to create vulnerabilities
There are seven methods you can use to create a vulnerability:
| Method | Best for |
| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **1.** [**Add manually**](#add-a-vulnerability-manually)**, using the writeups library** | Findings from manual testing, where a tester writes up what they found |
| **2.** [**Import**](#import-vulnerabilities) **from natively supported tools**, such as Nessus, Burp and Qualys | Scanner and tool output, especially large volumes |
| **3.** [**Import**](#import-vulnerabilities) **from CSV or JSON** | Output from tools without native support, or findings exported from other systems |
| **4. Create through the** [**Self-Service RESTful APIs**](https://docs.attackforge.com/) | Pipelines and integrations that push findings automatically |
| **5. Import from** [**Flows**](https://support.attackforge.com/app/modules/flows) | Automated workflows that create or transform findings |
| **6. Import from** [**Actions**](https://support.attackforge.com/app/actions) | Findings created by actions run from the project |
| **7. Create from** [**AI MCP**](https://support.attackforge.com/app/modules/ai-mcp-and-skills) | AI assistants and agents that create findings through AttackForge's MCP tools, for example while working through test cases |
## Who can create vulnerabilities
Only users with **Edit** access to the project can add vulnerabilities. That's usually the pentesters and security consultants.
## Things to know
* **Visibility follows project access.** You only see a vulnerability if you have access to a project it's linked to. Administrators are the exception and can see all vulnerabilities.
* **Projects can hold up to 10,000 vulnerabilities.** The limit makes sure reports can still be generated. If an import would go over it, use the Grouped option to combine findings.
* **Every vulnerability is linked to at least one asset.** When it's created, the vulnerability is assigned to at least one asset in the project's scope. If the asset isn't in scope, it's created automatically during imports.
## Vulnerabilities at a glance
However a vulnerability is created, it ends up as one consistent finding. It's linked to its affected assets and the test cases it failed, its priority drives SLAs and dashboards, its steps and evidence go into reports, and it feeds attack chains, portfolios and external systems such as ticketing tools.
## Add a vulnerability manually
Select `Create Vulnerability` from the project menu. The form has six required steps and five optional ones.
### 1. Choose a writeups library
Writeups are reusable, reviewed descriptions of vulnerabilities: the title, description, attack scenario and remediation advice. Starting from a writeup saves time, and every client gets the same quality of explanation for the same issue. Choose which library to search:
| Library | Contains |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **All Writeups** | Every writeup you have access to, across all libraries |
| **Main Vulnerabilities** | Most vulnerability writeups |
| **Imported Vulnerabilities** | Writeups for vulnerabilities imported from tools and scanners |
| **Project Vulnerabilities** | Writeups specific to this project, for information that shouldn't be shared outside it, or variations of other writeups (see Project-specific writeups) |
| **Custom libraries** | Any custom libraries you have access to |
### 2. Choose a writeup
Search the library by keyword, and hover over a writeup to preview its details on the right.
If nothing fits, select `Create Writeup` to add a new entry to the relevant library, so the next tester can reuse it.
{% hint style="info" %}
If you need to create a modified writeup for just your project - select the writeup and then click on `Duplicate` and select the `Project Library`
{% endhint %}
{% hint style="info" %}
If you need to modify a writeup in place - select the writeup and click `Edit`
{% endhint %}
### 3. Select the affected assets
Select one or more assets from the project's scope. Then choose how to record them:
| Option | Creates | Use it when |
| -------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **Individual** | A separate vulnerability for each affected asset | Each asset will be fixed and tracked by a different team, or assets need different priorities |
| **Grouped** | One vulnerability, linked to all the affected assets | The same issue appears on many assets, as is common in infrastructure tests |
You can mix both on the same project, with some vulnerabilities grouped and others individual.
**Why use Grouped:**
* it's more efficient on infrastructure tests, where one issue often affects dozens of hosts
* there are fewer vulnerabilities to manage, with no asset information lost
* there's less to quality review
In a grouped vulnerability, each asset can still have its own notes, tags and **affected components**. A component is the specific part of the asset that's affected, such as a URL, a port or a line of code, and components can have their own notes and tags too. Each asset can also be tracked and actioned individually, so you can follow remediation progress asset by asset.
Select which assets and components are affected:
The Affected Assets table will update to store the affected asset data:
Clicking on an asset will bring up more information including ability to modify components:
Clicking on a component will bring up more information on that affected component:
You can also Add or Import assets inline:
Adding provides the option to input freetext assets if the Assets module is disabled, or select from existing assets if the Assets module is enabled:
Importing provides various workflows to import from tools like NMAP and Masscan, generic formats like JSON and CSV, or a delimeted list of assets.
### 4. Set visibility
By default, a new vulnerability is visible to the whole project team straight away. This is deliberate: developers and asset owners can start fixing issues before the report is written, which reduces time to remediate.
If the finding needs checking first, set visibility to **Pending**. Pending works like a draft: only users with Edit access to the project can see it, which leaves time for quality, technical or peer review before the wider team sees it.
AttackForge autosaves new vulnerabilities automatically for you. You can access your drafts from the Vulnerabilities section on the project.
#### **Draft, Pending and Visible compared:**
| | Draft | Pending | Visible |
| ------------------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| **What it is** | A vulnerability that's still being written and hasn't been submitted yet | A created vulnerability that's being held back for review | A created vulnerability that's been released to the project team |
| **Who can see it** | Only its author | Only users with **Edit** access to the project | Everyone with access to the project, including clients and developers |
| **Typical use** | Saving work in progress, so a finding isn't lost before it's complete | Quality, technical or peer review before the wider team sees the finding | Getting findings to developers and asset owners quickly, to reduce time to remediate |
| **Counts in dashboards, SLAs and reports** | No | No | Yes |
| **Notifications sent** | No | No | Yes, to team members who've opted in to new vulnerability emails |
| **How it moves on** | The author completes and submits it, as Pending or Visible | A user with Edit access changes its visibility to Visible | It's already released. It can be set back to Pending if needed. |
| **Default?** | No | No. Choose it when you create the vulnerability. | Yes, the default for new vulnerabilities |
{% hint style="info" %}
Default to Visible or Pending can be configured globally within the Administration module.
{% endhint %}
### 5. Score the vulnerability
The project's settings decide which scoring systems are available.
* **Manual scoring** is always available, and testers can't have it turned off. Choose a **Likelihood of Exploitation**, from 1 (*difficult to exploit*) to 10 (*trivial to exploit*), and a **Priority**: Critical, High, Medium, Low or Info.
* **Scoring systems** enabled on the project, such as CVSS v3.1, CVSS v4, the OWASP Risk Rating Methodology, Microsoft DREAD, or a custom scoring system, have their own calculators. With CVSS, for example, the calculator works out the score, which sets the Likelihood of Exploitation and Priority automatically, and the score and vector string are added as tags.
* If the project uses **more than one scoring system**, AttackForge shows the score from each, and the tester picks the most suitable priority.
### 6. Write the steps to reproduce
The steps to reproduce, or proof of concept, are what developers use to confirm the issue and check their fix, so make them detailed enough to follow without asking you. The field is rich text, and HTML payloads are allowed.
### 7. Add notes (optional)
Add as many notes as you need, for example context for the reviewer or remediation tips for this particular environment.
### 8. Fill in custom fields (optional)
The custom fields and sections you see depend on how your organisation has configured the vulnerability form in the **Administration** module. They can change by type of testing. See Custom vulnerability forms.
### 9. Adjust tags (optional)
Tags are copied from the writeup, and you can add more. Using CVSS v3 scoring adds CVSS tags automatically. **Custom tags** let you add any key and value pair, such as `tls_weakness: protocol`, which you can then use for filtering, reporting or import mapping.
### 10. Link test cases (optional)
Link the vulnerability to the test case or cases it failed. Developers then see what was tested and why it failed, which helps them avoid making the same mistake again. Linking also marks the test cases as **Failed**, and they change to Remediated once the vulnerability is closed. You can link several test cases.
### 11. Add evidence (optional)
Upload files and supporting evidence.
When you create the vulnerability, it's assigned to the affected assets on the project.
## Project-specific writeups
Sometimes a standard writeup almost fits but needs changing for one project. For example, the description or remediation advice may need to refer to the client's own technology. Or a writeup may contain details that should only be visible on this project. A project-specific writeup lets you make those changes without altering the shared writeup everyone else uses.
1. Select the standard writeup you want to start from.
2. Select `Duplicate` → `Project Library`.
3. Make your changes and select `Update`.
4. Confirm the new project-specific writeup.
If nothing fits, select `Create Writeup` to add a new entry to the relevant library, so the next tester can reuse it.
You can also create a brand-new writeup straight in the Project Library.
## Custom vulnerability forms
Different kinds of testing need different information about each finding. A red team finding might need attack path details, while a PCI DSS finding needs the requirement it breaches. You can tailor the vulnerability form by testing type, such as web application, infrastructure, code review, red team, purple team or PCI DSS. Testers then only see the fields that apply. The custom fields also appear when anyone views the vulnerability so long as they have view access to the custom field.
This example adds a Red Team section that only appears on red team projects.
1. **Add a testing types field to projects.** In **Project Custom Fields**, create a multi-select field for testing types, such as `testing_types`.
2. **Add conditional fields to the vulnerability form.** In **Vulnerability Custom Fields**, create the fields or section, and give them a **Hide Expression** so they only show for the relevant testing type:
```
NOT ("Red Team" $in project.custom.testing_types)
```
The expression hides the section or field when the project has no testing types set, when none are selected, or when Red Team isn't one of them. In other words, the field only shows when **Red Team** is selected.
1. **Select the testing type on the project.** Create or edit a project and choose the testing type, such as `Red Team`.
2. **Create a vulnerability.** The Red Team section now appears on the form.
You can use the same approach to tailor the form for any other type of testing.
## Import vulnerabilities
Importing turns tool output into vulnerabilities in minutes. You don't retype scanner results, and with grouping, thousands of raw results become a manageable list of unique findings.
1. Select `Import Vulnerabilities` from the project's quick actions menu.
2. Select the tool, such as Nessus, Burp or Qualys.
3. Select the tool's output file. AttackForge parses it.
4. Select the vulnerabilities to import.
5. Choose **Individual** (one vulnerability per affected asset) or **Grouped** (vulnerabilities grouped automatically, one per issue). You can view the affected assets and each asset's component data, and configure the grouping rules.
{% hint style="info" %}
In the example shown, choosing **Grouped** reduced the number of vulnerabilities by **94%**, with the same data kept.
{% endhint %}
6. Select `Edit and Review` to check and adjust the vulnerabilities before they're imported.
7. Choose your import options, including dynamic parser actions and the writeups library to map to.
8. Import. Progress is shown as the import runs, and you'll see a summary with a link to the vulnerabilities when it's done.
**What's created automatically:**
* If a vulnerability doesn't match a writeup in the library, or can't be mapped to one, a new writeup is created.
* If an affected asset isn't in the project's scope, it's created.
Grouped vulnerabilities appear as single rows in vulnerability tables. Expand a row to see its affected assets.
### Custom import mapping
Custom import mapping matches imported vulnerabilities to writeups in your library, using expressions you write. Instead of importing a scanner's own wording, findings are matched to your reviewed, client-ready writeups. This lets you:
* combine several scanner findings into one unique writeup
* use writeups you know are good and ready for clients
* speed up QA and review
* avoid duplicate and near-duplicate entries in your library
**Example:** Nessus reports three separate findings: *SSL Version 2 and 3 Protocol Detection*, *TLS Version 1.0 Protocol Detection* and *TLS Version 1.1 Protocol Detection*. They're really one issue. With custom mapping, all three map to a single writeup, *Weak TLS Implementation*. These examples use the **Individual** import option.
#### Example 1: map on tags
```
vuln.tags.pluginID $in writeup.tags.pluginID
```
For each imported vulnerability, AttackForge checks each writeup in the selected library. If the vulnerability's `pluginID` tag is found in the writeup's `pluginID` tags, the vulnerability is mapped to that writeup. If no writeup matches, the vulnerability is imported as usual.
#### Example 2: map on custom tags
```
vuln.custom_tags.tls_weakness === writeup.custom_tags.tls_weakness
```
This works the same way as Example 1, but matches when the `tls_weakness` custom tag on the vulnerability exactly equals the one on the writeup.
The full list of datapoints and operators you can use is in [Reference: import mapping expressions](#reference-import-mapping-expressions).
## Tips and best practices
* **Start from a writeup.** Reviewed writeups give every client the same quality of explanation, and new ones you create help the next tester.
* **Group infrastructure findings.** Grouped vulnerabilities cut volume dramatically without losing asset detail, and each asset can still be tracked separately.
* **Use Pending for findings that need review.** Edit users can QA them before developers and clients see them.
* **Write steps to reproduce for the person fixing the issue.** Clear steps and inline screenshots mean fewer questions and faster fixes.
* **Always link test cases.** It sets test case results automatically and shows developers what was tested.
* **Map imports to your writeups.** Custom import mapping replaces scanner wording with your reviewed text and merges near-duplicates.
* **Use project-specific writeups for one-off changes,** rather than editing a shared writeup everyone relies on.
## FAQ
**I can't see Create Vulnerability.** You need Edit access to the project. Ask a Project Coordinator to check your access level.
**Should I use Individual or Grouped?** Use Grouped when the same issue affects many assets, as in most infrastructure tests. Use Individual when each asset will be fixed by a different team or needs a different priority. You can use both on one project.
**Why can't the client see a vulnerability I just created?** Its visibility may be set to Pending. Pending vulnerabilities are only visible to users with Edit access until they're released.
**Why can't I upload evidence yet?** Evidence can only be added once the vulnerability has been created. Create it first, then upload.
**My import created lots of new writeups. How do I stop that?** Writeups are created when an imported vulnerability doesn't match or can't be mapped to an existing one. Use custom import mapping to match imports to the writeups you already have.
**Is there a limit on vulnerabilities per project?** Yes, 10,000, so reports can still be generated. Grouping helps you stay well within it.
## Related pages
* [Test Cases](https://support.attackforge.com/app/getting-started/test-cases): linking vulnerabilities to test cases
* [Project Scope](https://support.attackforge.com/app/getting-started/project-scope): affected assets
* [Creating and Managing Projects](https://support.attackforge.com/app/getting-started/creating-and-managing-projects): scoring systems and SLAs
* [Reviewing and QA Vulnerabilities](https://support.attackforge.com/app/getting-started/reviewing-and-qa-vulnerabilities)
* [Writeups libraries](/app/modules/vulnerability-library.md)
* [Flows](https://support.attackforge.com/app/modules/flows) and [Actions](https://support.attackforge.com/app/actions)
* [Self-Service RESTful APIs](https://docs.attackforge.com/)
## Reference: import mapping expressions
### Imported vulnerability datapoints
| Datapoint | Type | Description |
| --------------------------------- | ------- | ------------------------------------------------------------------------------------ |
| `vuln.priority` | String | Critical, High, Medium, Low or Info |
| `vuln.title` | String | Title of the vulnerability |
| `vuln.tags.` | String | A tag on the vulnerability. The tag must use a colon separator, such as `key:value`. |
| `vuln.custom_tags.` | String | A custom tag. Replace `` with the custom tag's name. |
| `vuln.likelihood_of_exploitation` | Integer | 1 to 10 |
| `vuln.description` | String | Description |
| `vuln.attack_scenario` | String | Attack scenario |
| `vuln.remediation_recommendation` | String | Remediation recommendation |
| `vuln.custom_field.` | String | A custom field. Replace `` with the custom field's key. |
| `vuln.proof_of_concept` | String | Steps to reproduce |
| `vuln.import_source` | String | Import source of the vulnerability |
| `vuln.import_source_id` | String | Import source ID of the vulnerability |
### Writeup datapoints
| Datapoint | Type | Description |
| ------------------------------------ | ------- | ------------------------------------------------------------------------------ |
| `writeup.title` | String | Title of the writeup |
| `writeup.tags.` | String | A tag on the writeup. The tag must use a colon separator, such as `key:value`. |
| `writeup.custom_tags.` | String | A custom tag. Replace `` with the custom tag's name. |
| `writeup.likelihood_of_exploitation` | Integer | 1 to 10 |
| `writeup.description` | String | Description |
| `writeup.attack_scenario` | String | Attack scenario |
| `writeup.remediation_recommendation` | String | Remediation recommendation |
| `writeup.custom_field.` | String | A custom field. Replace `` with the custom field's key. |
| `writeup.import_source` | String | Import source of the writeup |
| `writeup.import_source_id` | String | Import source ID of the writeup |
### Operators
| Operator | Meaning |
| ----------------- | --------------------------------------------------------------- |
| `NOT` or `!` | Negation |
| `AND` or `&&` | And |
| `OR` or `\|\|` | Or |
| `==` | Equivalent (loose comparison) |
| `===` | Equal (strict comparison) |
| `!=` | Not equivalent (loose comparison) |
| `!==` | Not equal (strict comparison) |
| `>` `<` `>=` `<=` | Comparisons |
| `( )` | Grouping. Use `!( )` to negate a group. **\[Confirm]** |
| `$in` | Value is in a list, or partly matches |
| `$nin` | Value is not in a list |
| `=~ /RegEx/i` | Regular expression match, for example `writeup.title =~ /SSL/i` |
### Example expressions
| Expression | Matches when |
| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `writeup.title $in vuln.title` | The writeup's title fully or partly matches the vulnerability's title. For example, *Out-of-date Version (React)* and *Out-of-date Version (Bootstrap)* both match a writeup titled *Out-of-date Version*. |
| `vuln.tags.pluginID $in writeup.tags.pluginID` | The vulnerability's `pluginID` tag is in the writeup's `pluginID` tags |
| `vuln.custom_tags.tls_weakness === writeup.custom_tags.tls_weakness` | The `tls_weakness` custom tags are exactly equal |
| `(vuln.tags.pluginID $in writeup.tags.pluginID) OR (vuln.tags.someID $in writeup.tags.pluginID)` | Either the vulnerability's `pluginID` or its `someID` tag is in the writeup's `pluginID` tags |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://support.attackforge.com/app/getting-started/creating-vulnerabilities.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
