> 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/modules/writeups.md).

# Writeups

## Overview

Writeups make up your vulnerability library: centralised libraries of vulnerability descriptions that let you create vulnerabilities on projects quickly. Think of them as a knowledge base. Each writeup is a reusable template, so you write an issue once and use it on every project, saving reporting time.

Writeups come from MITRE, your own team, imports, and tools and scanners. They're stored in four kinds of library, each with its own access. When a tester uses a writeup, the vulnerability is linked to it, so a change to the writeup updates every linked vulnerability.

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2Fb5wKHjVfwg3y1fYE03Ig%2Fwriteups-at-a-glance.svg?alt=media&amp;token=0ad87ee8-d674-4fec-a66c-0f582090bb02" alt=""><figcaption></figcaption></figure>

Writeups are linked to vulnerabilities, not copied. Each vulnerability keeps a direct relationship with its writeup. This helps you:

* **update once, everywhere.** Changes to a writeup flow through to every linked vulnerability.
* **review faster.** Together with access controls, linking speeds up quality review of a pentest.
* **find unique vulnerabilities.** Vulnerabilities from the same writeup are the same issue, so you can tell which issues are unique.

## Why it matters

* **Consistent reports.** Every tester describes the same issue the same way, in your approved wording.
* **Faster testing.** Testers pick a writeup instead of writing from scratch.
* **Better data.** Linked vulnerabilities make it easy to count how often each issue appears, across projects and clients.
* **Controlled access.** Libraries keep sensitive or project-specific writeups away from people who shouldn't see them.

## Who uses it

| Who                                    | To                                                         |
| -------------------------------------- | ---------------------------------------------------------- |
| **Testers**                            | Create vulnerabilities from writeups, and suggest new ones |
| **Technical writers and QA reviewers** | Write and maintain approved writeups                       |
| **Administrators**                     | Set up libraries and control who can use and change them   |
| **Developers and engineers**           | Learn how to fix an issue, including with SecDim sandboxes |

## The four kinds of library

| Library              | What it holds                                                                                                                                                              | Who can use it by default                                  |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Main Library**     | Your primary writeups. Comes with more than 2,500 writeups from [MITRE CWE](https://cwe.mitre.org/) and [MITRE CAPEC](https://capec.mitre.org/), and you can add your own. | Shared: anyone who can create vulnerabilities on a project |
| **Imported Library** | Writeups imported from tools and scanners                                                                                                                                  | Shared: anyone who can create vulnerabilities on a project |
| **Project Library**  | Writeups assigned to specific projects, to keep project-specific or sensitive data apart from the shared libraries                                                         | Only people with access to the project                     |
| **Custom Libraries** | Libraries you create for particular test types, teams, testers or technologies                                                                                             | As configured                                              |

Administrators can restrict access to any library by role, group or user in the Administration module. Custom libraries are also set up there. See [Concepts and Access](https://support.attackforge.com/app/getting-started/concepts-and-access).

{% hint style="info" %}
**Important:** people without Edit access to at least one writeup library can't import vulnerabilities on a project.
{% endhint %}

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2F42tPuVfL2wM8FDQb5fvE%2FScreenshot%202026-11-10%20at%202.54.02%E2%80%AFpm.png?alt=media&amp;token=a96c7051-11dd-45c8-be39-b0f3ef584179" alt=""><figcaption></figcaption></figure>

## Create a writeup

1. Click `New`.
2. Choose a library: `Main`, `Imported`, `Project` or `Custom`.
3. For `Imported`, add details about the tool the writeup comes from.
4. For `Project`, link the writeup to at least one project. Only people with access to those projects can use it.
5. Enter the writeup's details. To save time, search for an existing writeup to pre-fill the fields.
6. Optionally, set a placeholder CVSS score. It's loaded when someone selects the writeup.
7. Optionally, add tags and custom tags, with any name and value. These help with custom report sections and exports to other tools.
8. Fill in any custom fields set up for writeups. See [Custom fields and forms](https://support.attackforge.com/app/getting-started/custom-fields-and-forms#vulnerability-custom-fields).

{% hint style="info" %}
You can also create writeups *just-in-time* when [Creating a Vulnerability](https://support.attackforge.com/app/getting-started/creating-vulnerabilities#add-a-vulnerability-manually) or [Importing Vulnerabilities](https://support.attackforge.com/app/getting-started/creating-vulnerabilities#import-vulnerabilities).
{% endhint %}

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FOlteZbvngb1mByiLxljs%2FScreenshot%202026-11-10%20at%202.57.31%E2%80%AFpm.png?alt=media&amp;token=c6b137ed-08d7-41e8-bc40-91b0344a4bb2" alt=""><figcaption></figcaption></figure>

## Find writeups

| View                  | What it shows                                           |
| --------------------- | ------------------------------------------------------- |
| **My Writeups**       | Every writeup you've created                            |
| **All Writeups**      | Every writeup you have access to                        |
| **Draft Writeups**    | Every writeup you're working on                         |
| **Custom Libraries**  | Writeups in custom libraries                            |
| **Archived Writeups** | Every archived writeup. Only Administrators can see it. |

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FM1cpS1R6joyZQalr4Now%2FScreenshot%202026-11-10%20at%202.58.26%E2%80%AFpm.png?alt=media&amp;token=5a1cd108-6c11-42cc-b647-7ddf8c15f62c" alt=""><figcaption></figcaption></figure>

## Update a writeup

Click `Edit` on a writeup to change it at any time. You can change it from the Writeups module, or when editing a vulnerability.

{% hint style="info" %}
**Note:** changes apply to every linked vulnerability, on every linked project.
{% endhint %}

## Move writeups between libraries

1. Select the writeups.
2. In the actions menu, click `Reassign`.
3. Choose the library to move them to.

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2F4kvNNv3cLMK61n27TguP%2FScreenshot%202026-11-10%20at%203.01.49%E2%80%AFpm.png?alt=media&amp;token=9510349e-df26-43ae-b116-29c708f85624" alt=""><figcaption></figcaption></figure>

## Archive a writeup

Archive writeups you no longer want people to use.

1. In the writeup's actions menu, select `Archive`.
2. The writeup moves to `Archived Writeups`.

Archived writeups can't be selected for new vulnerabilities, or for changes to existing ones. They stay referenced on existing projects, so those projects aren't affected. Administrators can restore an archived writeup when needed.

## Import writeups

AttackForge has prepared knowledge bases you can import. They're available on [GitHub](https://github.com/AttackForge/Writeups).

1. Click `New -> Import Writeups`.
2. Choose where the writeups come from:

| Source   | Use it to                                       |
| -------- | ----------------------------------------------- |
| **JSON** | Import from any source, using the JSON template |
| **CSV**  | Import from any source, using the CSV template  |

3. Select the writeups to import.
4. Optionally, edit them before importing.
5. Choose the library to import them into.
6. Watch the import's progress.

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2F4eLB7hVHAgaMrvSFNZiw%2FScreenshot%202026-11-10%20at%203.06.33%E2%80%AFpm.png?alt=media&amp;token=b8f00750-bcca-4491-8f85-3ac9a8b13b1f" alt=""><figcaption></figcaption></figure>

## Import with the API or AI MCP

You can also create and update writeups without the import screen:

| Method                       | Use it to                                                                                                                                                                                                                                            |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Self-Service RESTful API** | Create and update writeups from your own systems or scripts, such as syncing a knowledge base you maintain elsewhere. See [Self-Service RESTful API](https://support.attackforge.com/app/automations-and-integrations/self-service-restful-api).     |
| **AI MCP**                   | Let AI assistants and agents find, create and update writeups for you, such as drafting a new writeup from a tester's notes for review. See [AI MCP and skills](https://support.attackforge.com/app/automations-and-integrations/ai-mcp-and-skills). |

You need access to the API methods or MCP tools you use, and Edit access to the library you're writing to.

## **Enrich and proofread writeups with AI agents**

AI agents connected through MCP can also improve the writeups you already have. For example, an agent can:

* **enrich writeups**, such as adding remediation steps for specific languages and frameworks, references, CWE or CAPEC mappings, or a placeholder CVSS score
* **proofread writeups**, fixing spelling, grammar and tone, and keeping them in your house style
* **check consistency** across a library, such as finding duplicate writeups or ones with missing fields

Because writeups are linked, every improvement flows through to every linked vulnerability. Review an agent's changes before they're used in reports, for example by having it work in a custom library for review, then moving approved writeups to the Main Library. These uses are examples.

## Import MITRE writeups

Two MITRE knowledge bases are available:

* [MITRE CWE](https://github.com/AttackForge/Writeups/tree/main/MITRE/CWE)
* [MITRE CAPEC](https://github.com/AttackForge/Writeups/tree/main/MITRE/CAPEC)

Import them with `New -> Import Writeups`.

## Help developers fix issues with SecDim sandboxes

AttackForge is the only Offensive Security Management Platform to offer Secure Code Learning, in collaboration with [SecDim](https://secdim.com/).

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FvYxTqRFsPe7uJp3ibBer%2FScreenshot%202026-11-10%20at%203.28.25%E2%80%AFpm.png?alt=media&amp;token=48d2e91d-9d70-4134-9df1-0e02bc1b9b83" alt=""><figcaption></figcaption></figure>

SecDim sandboxes let you:

* explore real vulnerabilities in cloud-native apps, debug them, and check that patches work
* help developers learn how to fix vulnerabilities during a pentest
* help engineers and security teams work together on remediation
* improve retest pass rates
* test knowledge of common fixes, and measure how effective it is

Every sandbox includes a security test suite that simulates exploitation. Sandboxes work with `git`, so you can save your progress and pick up where you left off. SecDim's catalogue is based on real-world issues, and covers AI, GraphQL, React, Kubernetes and Web3. Each sandbox runs in a secure, isolated cloud development environment in your browser, where you can debug, patch and test code.

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FXsoh2DvdgTqiuNmDYL7C%2FScreenshot%202026-11-10%20at%203.13.06%E2%80%AFpm.png?alt=media&amp;token=714d3e79-6358-4d69-bce9-6f8fb359353f" alt=""><figcaption></figcaption></figure>

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FY8ksIUSMYPhW0ESW449W%2FScreenshot%202026-11-10%20at%203.12.57%E2%80%AFpm.png?alt=media&amp;token=667a503b-33cf-46c0-b4eb-2959ac43c769" alt=""><figcaption></figcaption></figure>

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FmOyK9AuqO6ximFphLlyS%2FScreenshot%202026-11-10%20at%203.25.59%E2%80%AFpm.png?alt=media&amp;token=7d117efe-ff61-4dae-a0e3-c5a1a1aefd8c" alt=""><figcaption></figcaption></figure>

### Use SecDim with writeups

1. Learn about the integration, then turn it on when you're ready.
2. Search SecDim's catalogue, and link sandboxes to your writeups. [Watch how](https://youtu.be/E8X9017GXI8).
3. When someone creates a vulnerability from a linked writeup, they see the linked sandboxes and can launch one. [Watch how](https://youtu.be/mnsjLeV_gRc).

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FWp2q6Wfo9mYyq5RMw1EF%2FScreenshot%202026-11-10%20at%203.30.46%E2%80%AFpm.png?alt=media&amp;token=ab2203bb-aa48-4095-b0ed-fc03574dd6e1" alt=""><figcaption></figcaption></figure>

## Tips

* **Start from the MITRE writeups**, then tailor them to your house style instead of writing from scratch.
* **Use the Project Library for anything sensitive** or specific to one client.
* **Use custom libraries for each team or test type**, and give access through groups.
* **Set a placeholder CVSS score** so testers start from a sensible default.
* **Use tags for reporting.** They help with custom report sections and exports.
* **Edit with care.** Changing a writeup changes every linked vulnerability on every project.
* **Archive, don't delete.** Archived writeups stay referenced on existing projects, and Administrators can restore them.
* **Make sure testers have Edit access to at least one library**, or they can't import vulnerabilities.

## FAQ

**Are writeups copied into vulnerabilities?** No. They're linked, so each vulnerability keeps a direct relationship with its writeup.

**If I edit a writeup, what changes?** Every linked vulnerability, on every linked project.

**How many writeups come with AttackForge?** More than 2,500, from MITRE CWE and MITRE CAPEC, in the Main Library.

**Who can use the Main and Imported libraries?** By default, anyone who can create vulnerabilities on a project. Administrators can restrict access.

**Who can use a Project Library writeup?** Only people with access to the projects it's linked to.

**Why can't a tester import vulnerabilities?** They need Edit access to at least one writeup library.

**What happens to vulnerabilities when I archive a writeup?** Nothing. The writeup stays referenced on existing projects. It just can't be used for new vulnerabilities or changes to existing ones.

**Can I import writeups from a spreadsheet?** Yes. Use the CSV template with `New -> Import Writeups`. JSON is supported too.

## Related pages

* [Concepts and Access](https://support.attackforge.com/app/getting-started/concepts-and-access)
* [Custom fields and forms](https://support.attackforge.com/app/getting-started/custom-fields-and-forms)
* [Vulnerabilities](https://support.attackforge.com/app/modules/vulnerabilities)
* [Groups](https://support.attackforge.com/app/modules/groups)
* [Reporting](https://support.attackforge.com/app/getting-started/reporting)
* [AttackForge Writeups on GitHub](https://github.com/AttackForge/Writeups)


---

# 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/modules/writeups.md?ask=<question>&goal=<user_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.
