Summary: Manage and apply regex-based parsers to extract structured information from tool output.

Using Parsers

The parser command manages and applies regex-based parsers to extract structured information (called "findings") from unstructured text, such as the output of a tool. These findings are then saved to the currently loaded report.

Core Concepts

  • Parser: A collection of rules stored in a JSON file (e.g., data/parsers/common.json).
  • Rule: A single regex pattern within a parser, identified by a name (e.g., ipv4_address).
  • Logbook Entry: The source of the text to be parsed. Every command run via pwn ... now or pwn ... bg creates a logbook entry with a unique ID.
  • Finding: A piece of information (a match) extracted by a rule, which is then stored in the loaded report.

Common Workflow

1. Run a tool and generate output

The output of every command is automatically saved to the logbook.

pwn web-scan now
# Let's assume this produced a Logbook Entry with ID 3a8f...

2. Apply a parser to the output

Use parser apply with the name of the parser and the ID of the logbook entry.

report load my-project-report
parser apply common 3a8f

pwnity will then run all regex rules from the common parser against the output of log entry 3a8f....

3. Review and Save Findings

If matches are found, you will be presented with an interactive checklist allowing you to select which findings to save to the currently loaded report.

4. View the Report

The new findings will now appear in the "Parser Findings" section of your report.

report show

Managing Parsers

Commands:

  • parser list: Shows all available parsers.
  • parser show <name>: Displays the rules for a specific parser.
  • parser add <name>: Creates a new, empty parser file.
  • parser update <name> ...: Adds or modifies rules and their regex patterns.
  • parser destroy <name>: Deletes a parser file.

Defining a Custom Parser

While pwnity comes with some common parsers, the real power lies in creating your own. Here’s how to create a simple parser to extract IP addresses.

1. Create the Parser

This creates the JSON file in data/parsers/.

parser add custom-ips

2. Add a Rule

A parser is a collection of rules. Let's add one called ipv4.

parser update custom-ips add-rule ipv4

3. Define the Regex Pattern

Now, assign the regular expression that will find the data.

parser update custom-ips ipv4 regex "\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b"

4. (Optional) Add Exclusion Patterns

You can add patterns to exclude certain matches. For example, to ignore the loopback address.

parser update custom-ips ipv4 exclude "^127\.0\.0\.1$"

5. View Your Parser

Use parser show to see the complete result.

parser show custom-ips