> For the complete documentation index, see [llms.txt](https://docs.alpha-security.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alpha-security.app/integrations/sysreptor-design.md).

# SysReptor Design Reference

Technical reference for how Alpha maps findings to SysReptor's finding schema. For setup instructions, see the [SysReptor Integration](/user-guide/sysreptor.md) user guide.

## One-time setup

1. In SysReptor, create (or duplicate the **Demo Design**) a design to use for Alpha reports. Make sure its **finding fields** include the IDs in the table below. The standard predefined fields already cover all of them.
2. Copy the **design ID** (visible in the design's URL / API).
3. In Alpha, open an engagement > **Reports** tab > **SysReptor** settings:
   * Set the **global default** (admin): base URL, the design ID, and an **API token** (SysReptor > user > API tokens). The token is write-only — Alpha never returns it.
   * Optionally set a **per-engagement override** (different server/design/token for one client).
4. Create a report, select & order findings, then **Push to SysReptor** and **Download PDF**.

## Field mapping

When Alpha pushes findings, each finding's data is mapped to SysReptor's finding `data` object:

| SysReptor field ID    | Type          | Source in Alpha                                                                         | Authored in |
| --------------------- | ------------- | --------------------------------------------------------------------------------------- | ----------- |
| `title`               | string        | Finding title                                                                           | Alpha       |
| `severity`            | enum          | Finding severity (info/low/medium/high/critical)                                        | Alpha       |
| `cvss`                | cvss          | Optional CVSS vector (v3.1/v4.0)                                                        | Alpha       |
| `description`         | markdown      | Finding description (+ inline evidence when the audited *include secrets* toggle is on) | Alpha       |
| `impact`              | markdown      | Finding impact                                                                          | Alpha       |
| `references`          | list\<string> | Finding references (CWE IDs / URLs)                                                     | Alpha       |
| `affected_components` | list\<string> | Targets of the finding's `affects` edges                                                | Alpha       |
| `recommendation`      | markdown      | Left empty for you to fill in SysReptor                                                 | SysReptor   |
| `summary`             | markdown      | Left empty for you to fill in SysReptor                                                 | SysReptor   |

If your design derives severity from CVSS instead of a standalone `severity` field, that works fine — Alpha still sends `severity`; SysReptor ignores fields the design doesn't define.

## Upsert behavior

Alpha creates one SysReptor project per report (stored as `sysreptor_project_id`) and **updates** findings on re-push (tracked by an Alpha-node to SysReptor-finding ID map), so re-pushing does not create duplicates. If the project was deleted in SysReptor, Alpha recreates it.

## Non-clobbering merge

Finding updates **merge** Alpha-owned fields over the existing finding `data`, so SysReptor-authored fields (`recommendation`, `summary`, executive summary) survive a re-push.

## Redaction

Secret values are redacted by default. Inline evidence excerpts (raw tool output) are included **only** when the report's audited *include secrets* toggle is on.

## SysReptor-owned content

Executive summary, remediation details, branding, and PDF rendering all live in SysReptor by design. Alpha does not attempt to author or overwrite these.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.alpha-security.app/integrations/sysreptor-design.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.