# Cyber Forensic Service (XG CFS)

> XG CFS provides all available cyber forensic Spectra Intelligence XG metadata for the requested sample(s) on the T1000 XG appliance.

## Introduction

XG CFS provides all available cyber forensic Spectra Intelligence XG metadata for
the requested sample(s) on the T1000 XG appliance. The service supports single and
bulk queries.

## XG CFS Single Query

Returns information for a single hash.

### Request

- Requests can be sent using the GET method or the POST method.
- Both methods use Basic Authentication. 
- Both methods support specifying hashes in the URL.
- POST allows specifying hashes in the request body as form data.

```
GET /api/xg/cfs/1/hashinfo/lookup.{format}
```

```
POST /api/xg/cfs/1/hashinfo/lookup.{format}
```

Path parameters:

- `format`: Specifies the response format. Supported values: `xml`, `json`

Query parameters:

- `md5`
- `sha1`
- `sha256`

Examples:

```
GET /api/xg/cfs/1/hashinfo/lookup.json?sha1=550a0e228ff317c74d62b668d260eb0a60bfeb39
```

### Response 

```json5
{
  "hashinfo": {
    "peheadermetadata": { 
      "version": "",
      "description": "",
      "language": "",
      "companyname": "",
      "originalname": "",
      "codepage": "",
      "productname": "",
      "productversion": "",
      "fileversion": ""
    },
    "fileinfo": { 
      "firstseendateutc": "2024-12-09T16:49:11Z",
      "iscontainer": false,
      "crc32": "",
      "filesizebytes": 11401,
      "ssdeep": "",
      "md5": "9c966d6b81788f1a0026aef16355927a",
      "sha1": "00020c16c9a3f1ba16f0d339bdca3d64af4eb12a",
      "ispeformat": false,
      "firstseenname": "",
      "sha256": "fc2a50fff96621a8e72916d4feca6aaf773da8eb17422f1a9645348ee9f28c8a",
      "isexecutable": false
    },
    "trust": 8,
    "threat": 0,
    "certificate": { 
      "commonname": "",
      "certificateexinfo": {
        "validfromdateutc": "",
        "publisher": "",
        "issuerthumbprint": "",
        "name": "",
        "serialnumber": "",
        "validtodateutc": "",
        "thumbprint": ""
      }
    }
  },
  "request": "/api/xg/cfs/1/hashinfo/lookup.json?sha1=00020c16c9a3f1ba16f0d339bdca3d64af4eb12a"
}
```

The response contains one top-level `hashinfolookup` object for the requested
hash. The `request` object contains the data submitted in the request.

The response code 404 is returned with a message "Missing Hashinfo for sample"
when a hash is not found in the database.

`hashinfo.certificate`

- `certificateexinfo`:  Detailed view of certificate information for the requested hash. 
  Contains metadata such as thumbprint of certificate issuer, certificate name, certificate
  publisher (organization name), certificate serial number, certificate thumbprint, date the
  certificate is valid from (in UTC), date the certificate is valid until (in UTC).
- `commonname`: The certificate common name.

---------------

`hashinfo.fileinfo`

- `crc32`:              CRC32 value of the requested hash.
- `filesizebytes`:      Sample size in bytes.
- `iscontainer`:        Indicates whether or not the requested sample 
                        is a container.
- `isexecutable`:       Indicates whether or not the requested sample 
                        is executable.
- `ispeformat`:         Indicates whether or not the file format of the 
                        requested sample is PE (Portable Executable).
- `firstseendateutc`:   First seen date of the requested sample (in UTC).
- `firstseenname`:      First seen name of the requested sample.
- `md5`:                MD5 value of the requested sample.
- `sha1`:               SHA1 value of the requested sample.
- `sha256`:             SHA256 value of the requested sample.
- `ssdeep`:             SSDEEP value of the requested sample (if available).

----------------

` hashinfo.peheadermetadata`

- `codepage`:       Codepage metadata from the PE header of the requested sample.      
- `companyname`:    Company name metadata from the PE header of the requested sample.  
- `description`:    Description metadata from the PE header of the requested sample.   
- `fileversion`:    File version metadata from the PE header of the requested sample.  
- `language`:       Language metadata from the PE header of the requested sample.      
- `originalname`:   Original name metadata in the PE header of the requested sample.   
- `productname`:    Product name metadata in the PE header of the requested sample.    
- `productversion`: Product version metadata in the PE header of the requested sample. 
- `version`:        Version metadata from the PE header of the requested sample.       

## XG CFS Bulk Query

This query retrieves nearly identical data as the single query does, but for
multiple sample hashes within a single response. It is more network-efficient
compared to multiple single queries.

### Request

- Requests can be sent using the GET method or the POST method.
- Both methods use Basic Authentication. 
- Both methods support specifying hashes in the URL.
- POST allows specifying hashes in the request body as form data.

```
GET /api/xg/cfs/1/hashinfos/lookup.{format}
```

```
POST /api/xg/cfs/1/hashinfos/lookup.{format}
```

Path parameters:

- `format`: Specifies the response format. Supported values: `xml`, `json`

Query parameters:

- `md5`
- `sha1`
- `sha256`

When requesting a list of hashes, they should be submitted as multiple
`hash_type=hash_value` pairs. Hashes can be submitted as part of the request URL
or in the POST body (form data).

The hashes can be serialized in one or both of the following ways:

1. One argument, comma-separated list:

   A set of hashes may be a comma-delimited list in a single argument, like so:
   
   ```
   md5=hash1,hash2,hash3
   ```

2. Multiple arguments of the same type:

   A set of hashes may each be a separate argument of the same type, like so:

   ```
   md5=hash1&md5=hash2&md5=hash3
   ```

#### Examples

GET requests:

```
GET /api/xg/cfs/1/hashinfos/lookup.json?sha1=550a0e228ff317c74d62b668d260eb0a60bfeb39,a183f2a0906357488256945754592faa4bd4f7ba
```
```
GET /api/xg/cfs/1/hashinfos/lookup.json?sha1=550a0e228ff317c74d62b668d260eb0a60bfeb39&sha1=a183f2a0906357488256945754592faa4bd4f7ba
```

POST request:

```
POST /api/xg/cfs/1/hashinfos/lookup.json
```

Form data:

```
sha1=550a0e228ff317c74d62b668d260eb0a60bfeb39&sha1=a183f2a0906357488256945754592faa4bd4f7ba
```

### Response

```json5
{
  "totalcount": 1,
  "request": "/api/xg/cfs/1/hashinfos/lookup.json",
  "hashinfos": [
    {
      "certificate": {
        "commonname": "",
        "certificateexinfo": {
          "validfromdateutc": "",
          "publisher": "",
          "issuerthumbprint": "",
          "name": "",
          "serialnumber": "",
          "validtodateutc": "",
          "thumbprint": ""
        }
      },
      "requestsha1": "00020c16c9a3f1ba16f0d339bdca3d64af4eb12a",
      "peheadermetadata": {
        "version": "",
        "description": "",
        "language": "",
        "companyname": "",
        "originalname": "",
        "codepage": "",
        "productname": "",
        "productversion": "",
        "fileversion": ""
      },
      "isfound": true,
      "threat": 0,
      "fileinfo": {
        "firstseendateutc": "2024-12-09T16:49:11Z",
        "iscontainer": false,
        "crc32": "",
        "filesizebytes": 11401,
        "ssdeep": "",
        "md5": "9c966d6b81788f1a0026aef16355927a",
        "sha1": "00020c16c9a3f1ba16f0d339bdca3d64af4eb12a",
        "ispeformat": false,
        "firstseenname": "",
        "sha256": "fc2a50fff96621a8e72916d4feca6aaf773da8eb17422f1a9645348ee9f28c8a",
        "isexecutable": false
      },
      "trust": 8
    }
  ]
}
```

The response for the bulk request contains one `hashinfoslookup` object with one
`hashinfo` object for each requested hash.

The `hashinfo` object in the bulk query response contains identical fields from
the `hashinfo` object in the single query response. Additionally, the following
fields are returned only in the bulk query response:

- `totalcount`: Indicates how many hashes were submitted in the request.
- `isfound`:    For each requested hash, indicates if the hash was found in the
                ReversingLabs database. 
- Depending on the requested hash type, the response includes one of:
  - `requestmd5`
  - `requestsha1`
  - `requestsha256`
