Importing reports from 3rd party tools

Report Upload

The report-upload command allows you to import findings from both third-party tools and Xygeni scans into the Xygeni platform.

Typically, results from Xygeni scans are uploaded right away. However, in some cases, you might perform scans and save the results in JSON format to upload later using the report-upload command. This can be useful if the build runner lacks a network connection.

The command validates reports, normalizes findings, and converts them to the Xygeni standard format. It processes findings from different tools for prioritization, filtering, workflow, and remediation. The converted output can be optionally sent to the standard output or saved to a file for validation or baseline generation.

The syntax is:

xygeni report-upload
  [--show-formats]
  [--directory=<path>] [--name=<name>]
  [--prop=name:value [--prop=name:value]...]
  [--never-fail] [--[no-]upload]
  --report=<file> [--format=<format>] [--log-file=<logFile>] [--output=<output> [--compact]] ...
   [@<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:
  -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).

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 reports can be provided, so the -r|--report, -f|--format and -o|--output could be given in triples. Only -r|--report is required, the other flags are optional.

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.

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.

The command exits with 0 (OK) when the upload is successful, or with a non-zero exit code if an error occurs. After a successful upload, the command will output the scan code.

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 snyk report into xygeni, but do not upload. This could help to check the conversion performed before set in the 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 Checkmarx One report exported using cx results show command:

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

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 example before shows.