> 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/architecture/parsers.md).

# Parser Pipeline

Parsing happens server-side, not in the collector. This means parsers can be updated, improved, and re-run against historical data without re-collecting anything.

## How it works

When the server receives a run from the collector, it goes through three stages:

1. **Normalize** - Strip ANSI escape sequences and terminal control characters. De-wrap PTY output into clean text. The raw bytes are preserved separately; normalization only creates the text layer used for parsing and search.
2. **Parse** - The server checks its parser registry to find a parser that matches the tool. If the operator happened to use structured output (like nmap's `-oX`), the parser prefers that. Otherwise, it parses the normal stdout text. Every parser must have a stdout path.
3. **Fallback** - If no parser matches the tool, the run is stored with raw output only. Full-text search still works. Entities can be promoted manually.

## Parser types

Alpha has two kinds of parsers:

### Native parsers

Full-featured parsers written in TypeScript. These handle tools with complex output formats:

* nmap, httpx, nuclei, netexec, gobuster, ffuf
* impacket, smbclient, smbmap, sqlmap, nikto, wpscan
* ldapsearch, enum4linux-ng, certipy, bloodyad
* SharpHound / BloodHound.py (AD JSON import)

### Declarative packs

Line-by-line regex parsers defined with pattern matching. Good for tools with simple, consistent output formats:

* naabu, masscan, dnsx, subfinder
* gau, whatweb, feroxbuster
* kerbrute, rpcclient
* hashcat, john, hydra, medusa

## Re-parsing

You can re-parse any run from the web UI or API. This is useful when a parser is updated or added after the data was originally captured. Re-parsing replaces the old entities and creates fresh ones from the same raw output.

## Adding a new parser

Parsers live in `server/src/pipeline/parsers/` (native) and `server/src/pipeline/packs/` (declarative). Each parser declares which tool name(s) it handles and exports a parse function that takes normalized text and returns entities.

See the existing parsers for the pattern. Every parser needs a test file with sample stdout fixtures.


---

# 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/architecture/parsers.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.