Notice

This guide is for the original release of AQtive Guard. For the current AQG SaaS platform, go to the AQtive Guard User Guide.

Upload a trace and run an analysis using the API Client

Before uploading a trace, make sure you have:

• Installed the API Client. See installation instructions.

• Met the API Client Prerequisites in Getting Started.

Upload size limitations

When uploading PCAP files, consider the available memory on the analysis VM. For optimal performance, the recommended file size is within half of the server’s RAM. For example, on a 16-gigabyte RAM server, limit uploads to files not exceeding 8 gigabytes.

Caution

Exceeding the prescribed file size limit for PCAP uploads may result in server instability. It is strongly recommended to stay within the designated file size limit to maintain server stability and application performance.

Example

Use the following example as a guide for uploading a trace using the API client.

Bash

$ export CRYPTOSENSE_API_KEY=your_api_key
$ ./cs-api upload-trace \
    --verbose \
    --project-name "My Project" \
    --trace-file my_trace.cst.gz \
    --trace-name "my_trace.cst.gz $(date +'%Y-%m-%d %H:%M')" \
    --slot-name "$(hostname)"
    --analyze profile_id

A successful upload will return a response indicating your report is being generated:

Report 'Report for my_trace.cst.gz 2024-10-10 17:06' of ID 1234 is being generated

In the above query:

• project-name is the name of the project.
• trace-file is the trace file to be used.
• trace-name is the name to be used for the trace. In the example above, the trace name includes the date to make it unique.

Important

Trace names need to be unique when using the API client or the upload will fail. If you enter a name that isn’t unique in the AQtive Guard Web UI, the trace name will have a number appended to the end of it to make it unique.

• slot-name <name> is the name of the slot to which the trace should be added. If no slot exists with the provided name, a new slot will be created.

Important

If you don’t enter a slot name, the API client will name it after the trace type and upload in that same slot, even if you later upload a different trace name from a different host.

• analyze <profile_id> is the numeric ID of the profile to use during analysis. Use --list-profiles to retrieve the IDs of existing profiles. Refer to Find the profile ID.

Tip

Use the cs-api upload-trace --help command to get detailed information about the command-line options specific to the upload-trace command.

Find project information

For existing projects, you’ll find the information you need in the AQtive Guard Web Interface:

1. In the web interface, select Projects from the menu bar.
2. Select the desired project name to open the project Overview, then select the Reports tab.
3. The Reports table displays information for all the reports in the selected project, including the:
   • project-name at the top of the table
   • slot-name used for existing slots
   • trace-file used for the analysis

Tip

You can use the --slot-name ... command-line option to select the slot where you will upload the trace. If no slot exists with the name you enter, a new slot with this name will be created.