> For the complete documentation index, see [llms.txt](https://docs.xygeni.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xygeni.io/xygeni-products/application-security-posture-management-aspm/importing-reports-from-3rd-party-tools.md).

# Importing reports from 3rd party tools

Xygeni ASPM consolidates findings from many third-party security tools. There are **three ingestion paths**; pick whichever fits the tool and your pipeline best. They share the same loader+converter pipeline downstream, so findings normalise into the same Xygeni format regardless of how they arrived.

## The three ingestion modes

### 1. Convert + upload (default)

The scanner reads a report file the tool already produced (JSON, XML, SARIF, …), converts it to Xygeni's standard format, and uploads it.

```bash
xygeni report-upload -n MyApp -f sast-checkmarx -r reports/checkmarx.SAST.xml
```

Use this when the tool can write to disk (almost all of them) and your pipeline already runs the tool and stages its output. See [Report Upload](#report_upload) below for the full command reference.

### 2. Pull — fetch from the tool's API

The scanner calls the tool's API, fetches findings, and routes the result through the same loader+converter pipeline. No intermediate file on disk; credentials read from environment variables and redacted from logs.

```bash
export SONARCLOUD_URL=https://sonarcloud.io
export SONARCLOUD_TOKEN=squ_***
xygeni report-upload --pull -f sast-sonarcloud \
  --selector project_key=acme/web --selector branch=main
```

Use this when the tool exposes a findings API and you'd rather not stage intermediate files. Available for SonarQube/SonarCloud, Kiuwan, Checkmarx One, Prisma Cloud, and Wiz CNAPP. See [Pull-mode fetch](/xygeni-products/application-security-posture-management-aspm/importing-reports-from-3rd-party-tools/pull-mode-fetch.md) for the walkthrough and one worked example per tool.

### 3. Push — inbound webhook

The tool calls Xygeni's webhook on scan completion. Configured tool-side (no CLI invocation), with optional HMAC signature verification.

```
POST https://api.xygeni.io/api/v1/ingest/webhook
X-Xygeni-Format: <tool-format-id>
X-Xygeni-Token:  <UPLOAD_SCAN_RESULTS token>
```

Use this when the tool emits outbound webhooks and you'd rather not run anything CLI-side. A dedicated setup guide per supported tool will be added to this section as each webhook adapter ships.

### Picking a mode

| If…                                                                 | Use                |
| ------------------------------------------------------------------- | ------------------ |
| The tool produces a file your CI already collects                   | **convert+upload** |
| You'd rather not stage files; the tool has an API                   | **pull**           |
| You want the tool to push on scan completion without CLI invocation | **push**           |

The same tool can support multiple modes — e.g. SonarCloud works in convert+upload mode (with a downloaded `issues/search` JSON) and in pull mode (with the scanner driving the API itself).

***

## Report Upload <a href="#report_upload" id="report_upload"></a>

The `report-upload` command is the entry point for both convert+upload and pull modes. It validates reports, normalizes findings, and converts them to the Xygeni standard format. Findings then flow through prioritization, filtering, workflow, and remediation like any other Xygeni scan output.

{% hint style="info" %}
Typically, Xygeni scans upload their findings right away. The `report-upload` command exists so external scanner output (or older Xygeni scan files staged for later) can be uploaded the same way.
{% endhint %}

### Syntax

```bash
xygeni report-upload
  [--show-formats]
  [--directory=<path>] [--name=<name>]
  [--prop=name:value [--prop=name:value]...]
  [--never-fail] [--[no-]upload]
  # convert+upload mode (default): supply --report; repeat for multiple files
  --report=<file> [--format=<format>] [--log-file=<logFile>] [--output=<output> [--compact]] ...
  # pull mode: --pull replaces --report; --selector and --filter pass per-scan values
  --pull --format=<format> [--selector=k=v]... [--filter=k=v]...
   [@<filename>...]

Converts and uploads an external tool or xygeni scan reports into Xygeni platform.

Parameters:
      [@<filename>...]       One or more argument files containing options.
  -s, --show-formats         Show the formats supported.
  -n, --name=<name>          The software name. Inferred from directory when not provided.
  -d, --basedir=<path>       Base directory for resolving relative paths.
                             Default is the current working directory.
  -p, --prop=name:value      Properties for the software.
                             Name of standard properties are: business_value (or bizval), architecture (or arch),
                               business_area (or bizarea), product_unit (or product), and provider.
                             business_value should be one of: CRITICAL, HIGH, MEDIUM, LOW, INFO.
                             Additional custom properties may be added.
      --never-fail           Do not fail: always exit with code 0, even when report conversion or upload fails.
      --[no-]upload          Upload reports to server? (default: true)
                             Use --no-upload for testing report conversion.
Reports to upload (convert+upload mode):
  -r, --report=<file>        the report file to upload. Use '-' or 'stdin' for standard input.
  -f, --format=<format>      the format / type of the report to upload.
                             Use <tab> to get the available values, when autocomplete is active.
                             Optional. When not given, it will be inferred from the report.
  -o, --output=<output>      file for writing the output in Xygeni format.
                             Use '-' or 'stdout' for console output.
                             Optional. No output when not given.
      --compact              Use compact output (default: pretty-print).
  -l, --log-file=<logFile>   The xygeni scan logfile to upload (optional).
Pull mode:
      --pull                 Fetch the report from the tool API instead of reading a file.
                             Requires --format pointing to a registry entry with a pull: block.
      --selector=k=v         Per-scan identifier passed to the fetcher (e.g. project_key=acme,
                             branch=main, org_id=org-1234). Repeatable.
      --filter=k=v           Tool-specific filter (e.g. severity=CRITICAL,HIGH; status=open;
                             time_range_days=7). Repeatable.
```

{% hint style="info" %}
This command replaces the deprecated `xygeni util scan-upload` command.
{% endhint %}

To list the supported third-party tools and formats supported, run `xygeni report-upload --show-formats`.

The `-n | --name` option provides the project name the reports uploaded will be assigned to. It will be inferred if not provided. For a single xygeni report it will be extracted from the report metadata.

Multiple convert+upload reports can be provided in one invocation, so the `-r|--report`, `-f|--format` and `-o|--output` flags may be repeated. Pull mode takes exactly one `--format`; combine multiple pulls by issuing multiple commands.

The `-l|--log-file` only will be used for xygeni scan results and will be ignored otherwise.

The formats available are listed in the [external scanners support](/xygeni-products/application-security-posture-management-aspm/importing-reports-from-3rd-party-tools/external-scanners-supported.md) section and broken down per category — see [DAST Report Import](/xygeni-products/application-security-posture-management-aspm/importing-reports-from-3rd-party-tools/dast-report-import.md), [SAST Report Import](/xygeni-products/application-security-posture-management-aspm/importing-reports-from-3rd-party-tools/sast-report-import.md), [SCA Report Import](/xygeni-products/application-security-posture-management-aspm/importing-reports-from-3rd-party-tools/sca-report-import.md), [IaC Report Import](/xygeni-products/application-security-posture-management-aspm/importing-reports-from-3rd-party-tools/iac-report-import.md), [Secrets Report Import](/xygeni-products/application-security-posture-management-aspm/importing-reports-from-3rd-party-tools/secrets-report-import.md), and [Inventory Report Import](/xygeni-products/application-security-posture-management-aspm/importing-reports-from-3rd-party-tools/inventory-report-import.md).

{% hint style="info" %}
It is recommended to specify the format of the input report source using the `--format` option. However, for the majority of inputs, the `report-upload` function can automatically determine the input format.\
\
Only in certain cases report type inference may fail due to ambiguity. For example, with the SARIF format which can convey different scan types, or with multi-scan files generated by certain tools.
{% endhint %}

The scan *logfile* could be optionally uploaded to Xygeni, using the `--log-file` parameter.

The command returns **`0 (OK)`** exit code when the upload succeeded, or a non-zero exit code when there is an error. When the upload is successful, the scan code is printed as the output of the command.

{% hint style="info" %}
Please note that scan results are processed asynchronously so results may not be immediately available after the command concludes.
{% endhint %}

### Examples

* List the supported formats:

```bash
xygeni report-upload --show-formats
```

* Upload a Checkmarx SAST report (xml format):

```bash
xygeni report-upload --name=MyApp --format=sast-checkmarx --report=rep/checkmarx.SAST.xml
```

* Upload two previously generated xygeni reports:

```bash
xygeni report-upload -n MyApp \
       -r rep/xygeni.deps.json -l=rep/xygeni.deps.log \
       -r rep/xygeni.secrets.json -l rep/xygeni.secrets.log
```

* Convert a Snyk report into xygeni, but do not upload. Useful for verifying the conversion before wiring it into a CI/CD pipeline:

```bash
xygeni report-upload -n MyApp -r rep/snyk.json -f sca-snyk -o xygeni.sca.json --no-upload
```

* Upload SCA, SAST and IaC findings from a Checkmarx One report exported using `cx results show`:

```bash
xygeni report-upload -n MyApp \
  -r rep/cxOne_results.json -f sast-checkmarx-one-results \
  -r rep/cxOne_results.json -f sca-checkmarx-one-results \
  -r rep/cxOne_results.json -f iac-checkmarx-one-results
```

* Pull SonarCloud SAST findings via the API instead of staging a JSON file:

```bash
export SONARCLOUD_URL=https://sonarcloud.io
export SONARCLOUD_TOKEN=squ_***

xygeni report-upload --pull -f sast-sonarcloud \
  --selector project_key=acme/web --selector branch=main \
  --filter severity=CRITICAL,HIGH
```

See [Pull-mode fetch](/xygeni-products/application-security-posture-management-aspm/importing-reports-from-3rd-party-tools/pull-mode-fetch.md) for a full walkthrough of pull mode with one worked example per supported tool.

{% hint style="info" %}
When a tool report contains findings from different domains (code vulnerabilities, IaC flaws, hardcoded secrets…​), the same file with different formats could be repeated to extract and upload the findings of interest, as the Checkmarx One example above shows.
{% endhint %}


---

# 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:

```
GET https://docs.xygeni.io/xygeni-products/application-security-posture-management-aspm/importing-reports-from-3rd-party-tools.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.