API Documentation

Obtaining your API Key

All requests made to ACUBETotal requires an API Key. Get your API key by hovering over your username in the navigation bar once logged in and copying your key.

Uploading a sample

Upload a sample to ACUBETotal.

Request Format

curl --request POST \
  --url <acubetotal_baseurl>/api/submissions \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer <api-key>' \
  --form files=<sample/samples> \
  --form organisations=<orgs> \
  --form modules=<modules> \
  --form capeOptions='{"package":<analysis package>,"timeout":<timeout>,"options":<options>}' \
  --form zipOptions='{"zipType":<zipType>,"compoundEntryFile":<entryFile>,"password":<password>}' \
  --form tags=<tags> \
  --form fileTypeOptions='{"FileEntries":{"<fileName>":{"AutomationChoice":"<automationChoice>", "ManualEntry":"<filetype>"}}}'

Body Params

Field	Type	Description
sample/samples	binary	Malware sample to submit
modules	string	Modules to run on sample
analysis package	string	Type of malware. E.g. exe, Shellcode, Unpacker, zip...
timeout	integer	How long malware is run in Cape Sandbox in seconds. Leave 0 for Sandbox to run malware to finish.
options	string	Run options for Cape Sandbox
zipType	string	Type of sample submitted. E.g. bulk, compound.
entryFile	string	Filename of the entry file within the compound zip
password	string	Password of the zip file
tags	string	Tags to be associated with the submission
fileName	string	Filename of the sample being submitted
automationChoice	string	Whether automatic file type detection is enabled, E.g. auto, manual
filetype	string	The filetype of the sample. E.g. exe, elf.

Example Request

curl --request POST \
  --url https://acubetotal.stg.acube.sg/api/submissions \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer <api-key>' \
  --form files[]=@calc.exe \
  --form modules=floss,capa,capev2,opencti,elastic-opencti,elastic-cape \
  --form capeOptions='{"package":"exe","timeout":30,"options":""}' \
  --form zipType=bulk

Listing submissions

Get a paginated list of all submissions.

Request Format

curl --request GET \
  --header 'Authorization: Bearer 00000000-0000-0000-0000-000000000000' \
  --url '<acubetotal_baseurl>/api/submissions?page=<page>&rows=<rows>&orgs=<orgs>&submitter=<submitter>'

Query Params

Field	Type	Description
page	number	Page number (required)
rows	number	Number of submissions per page (default: 10)
orgs	string	Comma-delimited list of organizations to filter submissions by
submitter	string	Filter submissions by submitter name

Example Request

curl --request GET \
  --header 'Authorization: Bearer 00000000-0000-0000-0000-000000000000' \
  --url 'https://acubetotal.stg.acube.sg/api/submissions?page=1&rows=10'

Example Response

{
  "page": 1,
  "totalPages": 12,
  "perPage": 10,
  "total": 120,
  "data": [
    {
      "id": 5,
      "status": "COMPLETED",
      "modules": ["floss", "capa", "capev2"],
      "tags": ["case 1"],
      "organizations": ["ORG1"],
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Getting submission details

Get the full details of a specific submission.

Request Format

curl --request GET \
  --header 'Authorization: Bearer 00000000-0000-0000-0000-000000000000' \
  --url <acubetotal_baseurl>/api/submissions/<id>

Path Params

Field	Type	Description
id	number	Submission ID assigned by ACUBETotal

Example Request

curl --request GET \
  --header 'Authorization: Bearer 00000000-0000-0000-0000-000000000000' \
  --url https://acubetotal.stg.acube.sg/api/submissions/5

Updating a submission

Update tags, organizations, or rerun modules on a submission.

Request Format

curl --request PUT \
  --header 'Authorization: Bearer <api-key>' \
  --url <acubetotal_baseurl>/api/submissions/<id> \
  --form id=<id> \
  --form tags=<tags> \
  --form organizations=<organizations> \
  --form modules=<modules> \
  --form category=<category> \
  --form capeOptions='{"timeout":<timeout>,"machine":<machine>}'

Path Params

Field	Type	Description
id	number	Submission ID assigned by ACUBETotal

Body Params

Field	Type	Description
id	number	Submission ID (required)
tags	string	Comma-delimited list of tags to associate with the submission
organizations	string	Comma-delimited list of organizations for access control
modules	string	Comma-delimited list of additional modules to run
category	string	Modules to rerun: `none`, `failed`, or `all`
capeOptions	object	JSON format cape options for dynamic analysis
preScript	binary	Pre-script for dynamic analysis
duringScript	binary	During-script for dynamic analysis
c2Docker	binary	C2 docker script for dynamic analysis

Example Request

curl --request PUT \
  --header 'Authorization: Bearer 00000000-0000-0000-0000-000000000000' \
  --url https://acubetotal.stg.acube.sg/api/submissions/5 \
  --form id=5 \
  --form tags='case 1,case 2' \
  --form category=failed

Checking execution status

Check whether a submission has completed running for each module.

Request Format

curl --request GET \
  --header 'Authorization: Bearer 00000000-0000-0000-0000-000000000000' \
  --url <acubetotal_baseurl>/api/submissions/<id>/execution

Path Params

Field	Type	Description
id	string	Submission ID assigned by ACUBETotal

Example Request

curl --request GET \
  --header 'Authorization: Bearer 00000000-0000-0000-0000-000000000000' \
  --url https://acubetotal.stg.acube.sg/api/submissions/5/execution

Example Response

{
  "state": {
    "status": "PENDING",
    "steps": [
      {
        "parallel": [
          {
            "module": "floss",
            "inputs": { "file": "file" },
            "outputs": { "result-json": "floss-result" },
            "status": "COMPLETED",
            "jobId": "58189cbd4e6dc0c7d8e66b6a6f75652fc9f4afc7ce0eba7d67d8c3feb0d5381f",
            "error": null
          },
          {
            "module": "capa",
            "inputs": { "file": "file" },
            "outputs": { "result-json": "capa-result" },
            "status": "COMPLETED",
            "jobId": "58189cbd4e6dc0c7d8e66b6a6f75652fc9f4afc7ce0eba7d67d8c3feb0d5381f",
            "error": null
          },
          {
            "module": "capev2",
            "inputs": {
              "file": "file",
              "filename": "filename",
              "size": "size"
            },
            "outputs": {
              "report-json": "cape-report-json",
              "screenshots": "screenshots"
            },
            "status": "COMPLETED",
            "jobId": "837",
            "error": null
          }
        ]
      },
      {
        "parallel": [
          {
            "module": "opencti",
            "inputs": { "cape-report-json": "cape-report-json" },
            "outputs": { "opencti-report": "opencti-report" },
            "status": "PENDING",
            "jobId": null,
            "error": null
          },
          {
            "module": "elastic-cape",
            "inputs": { "report": "cape-report-json" },
            "outputs": {},
            "status": "COMPLETED",
            "jobId": null,
            "error": null
          }
        ]
      },
      {
        "parallel": [
          {
            "module": "elastic-opencti",
            "inputs": { "report": "opencti-report" },
            "outputs": {},
            "status": "PENDING",
            "jobId": null,
            "error": null
          }
        ]
      }
    ]
  }
}

The outputs object in each module's status shows what results are available for download. The values (e.g., floss-result, cape-report-json) are the keys to use with the download endpoint.

Rerun a submission

Rerun all modules ran or only modules that errored out on a submission.

Request Format

curl --request POST \
  --header 'Authorization: Bearer <api-key>' \
  --url <acubetotal_baseurl>/api/submissions/<id>/rerun?quantity=<quantity>

Path Params

Field	Type	Description
id	string	Submission ID assigned by ACUBETotal
quantity	string	Which modules to rerun. E.g. all, failed

Example Request

curl --request GET \
  --header 'Authorization: Bearer 00000000-0000-0000-0000-000000000000' \
  --url https://acubetotal.stg.acube.sg/api/submissions/6/rerun?quantity=all

Downloading raw results

Download individual results from each of the modules ran on a submission.

Request Format

curl --request GET \
  --header 'Authorization: Bearer <api-key>' \
  --url <acubetotal_baseurl>/api/submissions/<id>/download/<result>

Path Params

Field	Type	Description
id	string	Submission ID assigned by ACUBETotal
result	string	Desired report output to download

Available results to download

Static analysis:

FLOSS json output: floss-result
CAPA json output: capa-result
Detect-It-Easy json output: detect-it-easy-result
PE Info json output: pe-info-result
ELF Parser json output: elfparser-result
OleVBA json output: olevba-result
PeePDF json output: peepdf-result
EML Parser json output: eml-parser-result

Dynamic analysis (CAPEv2):

CAPE summary report: cape-report-json
CAPE full report: cape-full-report-json
Dynamic CAPA json output: dynamic-capa-result
Screenshots: screenshots
PCAP network capture: cape-pcap
Dropped files: dropped-files
Process dumps: process-dumps
Payload: payload
Windows event logs: cape-evtx

Other:

Original sample file: file
OpenCTI report: opencti-report
bSim result: bsim-result
ditu result: ditu-result

Discovering available results

The available results vary per submission depending on which modules were run and the sample type. See the outputs object in the execution status response - the values (e.g., floss-result, cape-report-json) are the keys to use with this download endpoint.

To download the original submitted sample file, use file as the result key.

Example Request

curl --request GET \
  --header 'Authorization: Bearer 00000000-0000-0000-0000-000000000000' \
  --url https://acubetotal.stg.acube.sg/api/submissions/5/download/cape-report-json

Getting available modules

Get the list of available modules and their dependencies.

Request Format

curl --request GET \
  --header 'Authorization: Bearer 00000000-0000-0000-0000-000000000000' \
  --url <acubetotal_baseurl>/api/pipeline/dependency-tree

Example Request

curl --request GET \
  --header 'Authorization: Bearer 00000000-0000-0000-0000-000000000000' \
  --url https://acubetotal.stg.acube.sg/api/pipeline/dependency-tree

Example Response

[
  {
    "display": "FLOSS",
    "module": "floss",
    "children": ["elastic-floss"],
    "parents": [],
    "checkedByDefault": true
  },
  {
    "display": "CAPA",
    "module": "capa",
    "children": ["elastic-capa"],
    "parents": [],
    "checkedByDefault": true
  },
  {
    "display": "CAPE Sandbox",
    "module": "capev2",
    "children": ["opencti", "elastic-cape"],
    "parents": [],
    "checkedByDefault": false
  }
]

Getting available CAPE machines

Get the list of available virtual machines for CAPE dynamic analysis.

Request Format

curl --request GET \
  --url <acubetotal_baseurl>/api/cape/machines

Example Request

curl --request GET \
  --url https://acubetotal.stg.acube.sg/api/cape/machines

Example Response

[
  {
    "os": "win10",
    "architectures": ["32bit", "64bit"]
  },
  {
    "os": "win7",
    "architectures": ["32bit"]
  }
]

API Documentation

Obtaining your API Key​

Uploading a sample​

Request Format​

Body Params​

Example Request​

Listing submissions​

Request Format​

Query Params​

Example Request​

Example Response​

Getting submission details​

Request Format​

Path Params​

Example Request​

Updating a submission​

Request Format​

Path Params​

Body Params​

Example Request​

Checking execution status​

Request Format​

Path Params​

Example Request​

Example Response​

Rerun a submission​

Request Format​

Path Params​

Example Request​

Downloading raw results​

Request Format​

Path Params​

Available results to download​

Discovering available results​

Example Request​

Getting available modules​

Request Format​

Example Request​

Example Response​

Getting available CAPE machines​

Request Format​

Example Request​

Example Response​

Obtaining your API Key

Uploading a sample

Request Format

Body Params

Example Request

Listing submissions

Request Format

Query Params

Example Request

Example Response

Getting submission details

Request Format

Path Params

Example Request

Updating a submission

Request Format

Path Params

Body Params

Example Request

Checking execution status

Request Format

Path Params

Example Request

Example Response

Rerun a submission

Request Format

Path Params

Example Request

Downloading raw results

Request Format

Path Params

Available results to download

Discovering available results

Example Request

Getting available modules

Request Format

Example Request

Example Response

Getting available CAPE machines

Request Format

Example Request

Example Response