Importing reports from 3rd party tools

Report Upload

The report-upload command may be used to import both findings from third-party tools and from Xygeni scans to the platform for processing.

Under normal circumstances, the findings from xygeni scans are uploaded immediately.In certain use cases, it is possible to run one or more scans and save the findings in the JSON format, and in a different point in time to upload the findings using the report-upload command. For example, the build runner could be isolated and hermetic (disconnected from network) for security, and the scan results produced could be uploaded later, when network connection is available.

The command validates the input report(s), normalizes the findings and convert them to the Xygeni standard format for each scan type, so findings from different tools could be processed for prioritization, filtering, workflow and remediation.The converted output could be optionally dumped to the standard output or to a file for validation or for generating a baseline.

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 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 supersedes the deprecated xygeni util scan-upload command.

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

The -n | --name option provides the project name the report(s) 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 could be provided, so the -r|--report, -f|--format and -o|--output could be given in triples. Only -r|--report is required, the others 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 inform the format of the input report source using the --format option, but for most of the inputs the report-upload can infer the input format. Only in certain cases report type inference may fail due to ambiguity. For example, with 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, in 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 upload is successful, the scan code is printed as the output of the command.

Please take into account that scan results are processed asynchronously and results may not be available immediately after the command terminates.

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 (package vulnerabilities, 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.