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.

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 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.

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

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.

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.

Syntax

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.

This command replaces the deprecated xygeni util scan-upload command.

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 section and broken down per category — see DAST Report Import, SAST Report Import, SCA Report Import, IaC Report Import, Secrets Report Import, and Inventory Report Import.

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.

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.

Please note that scan results are processed asynchronously so results may not be immediately available after the command concludes.

Examples

• List the supported formats:

xygeni report-upload --show-formats

• Upload a Checkmarx SAST report (xml format):

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

• Upload two previously generated xygeni reports:

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:

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:

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:

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 for a full walkthrough of pull mode with one worked example per supported tool.

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.