Nuix Collection Configuration API
The Collection Configuration API from Nuix — 2 operation(s) for collection configuration.
OpenAPI Specification
openapi: 3.0.1
info:
title: NUIX ECC REST API Command Reference Case Collection Configuration API
description: 'Welcome to the Nuix ECC REST API command reference. From here you can access all available ECC REST APIs. You can also send REST commands to your running ECC Server, as well as view the responses.
**Note\:** The Nuix ECC User Guide includes a gloassary which defines specialized terms such as `Case`, `Custodian` and `Target` which are mentioned throughout this command reference.
**Note\:** This command reference has been updated for Nuix ECC version 9.12.0.'
contact:
name: Nuix
url: https://nuix.github.io/sdk-docs/latest/
email: APISupport@nuix.com
license:
name: Licence
url: https://www.nuix.com/sites/default/files/20200210_EULA_v1.pdf
version: ${customer.version}
servers:
- url: '{protocol}://{address}:{port}/api/ecc'
variables:
protocol:
default: https
description: protocol for communication
enum:
- http
- https
address:
default: 127.0.0.1
description: The location which the ECC resides
port:
default: '80'
description: 80, 443 or alternative
security:
- BasicAuth: []
tags:
- name: Collection Configuration
paths:
/v2/configurations:
get:
tags:
- Collection Configuration
summary: Lists all Collection Configurations
description: 'Lists all Collection Configurations defined on the connected server, or a filtered list if optional query params are used.
**Note\:** In the response body, a Collect task type will be followed by an Evidence object, and optionally a FileType, DateRange, AdvancedSearch, Hash, Volatile, and RAM object.'
operationId: listConfigurations
parameters:
- name: id
in: query
description: 'The id of the configuration to list.
**Note\:** if `id` is specified, the `category` query parameter is ignored.'
required: false
schema:
type: integer
format: int32
- name: category
in: query
description: Optional category assigned to one or more configurations.
required: false
schema:
type: string
responses:
'200':
description: Successful Listing of Configurations
content:
application/json:
schema:
$ref: '#/components/schemas/listConfigurationsResponse'
examples:
targets_and_computers:
summary: Configuration with targets and computers
value:
- configurations:
- id: 101
name: Configuration Example
description: Example configuration with both targets and computers
template: Default
category: ''
targets:
- 106
- 142
computers:
- 5B05C769-6368-4608-A387-9525C4332B50
- E594B78A-15AD-4BA5-AB9D-68905B657DC6
hasInputs: false
tasks:
- taskNum: 0
taskType: Collect
impersonation: None
label: ''
Evidence:
destination: c:\collection
credentials: false
createFileSafe: true
compression: High
segmentSize: 2
segmentSizeUnit: GB
validateCollection: true
FileType:
analyzeSignatures: false
mode: Include
extensions:
- extension: ai
collectAll: false
- taskNum: 1
taskType: Relocate
impersonation: None
label: ''
SmartMover:
destinationFolder: c:\collection
destComputerName: AUSYD-L-NX0142
destComputerId: E21287F5-9E96-6CFF-0624-056AFA28E902
moveOrCopy: Move
relocateData: true
relocateLogs: true
'400':
description: Invalid Configuration ID
content:
application/json:
schema:
$ref: '#/components/schemas/standardResponse'
example:
code: 400
id: 101
message: Invalid Configuration ID supplied
'504':
description: Waiting for the model to load
content:
application/json:
schema:
$ref: '#/components/schemas/standardResponse'
example:
code: 504
id: 101
message: Waiting for the model to load
post:
tags:
- Collection Configuration
summary: Creates a new Collection Configuration based on an existing Collection Configuration
description: 'The new Collection Configuration is created with all tasks removed.
Tasks can be created in the new Collection Configuration by either creating a new task from scratch, or referencing an existing Task in any other Collection Configuration, which is then copied into the new Collection Configuration.
Copied tasks can be used as is, or modified.
**Note\:** credentials used for the destination are stored in the task (Collect or Relocate) part of a Collection Configuration, so if credentials are needed, the appropriate task should be copied into the new Collection Configuration.
### The following objects vary depending on the value of taskType\:
### taskType = Collect
If `parentConfigId` and `taskNum` values are *not* specified (i.e. a new task is being created), then an `Evidence` object must follow, with `FileType`, `DateRange`,
`AdvancedSearch`, `Hash`, `Volatile`, and `RAM` objects optional.
However, if a `parentConfigId` and `taskNum` *are* specified, then all following objects are optional, and required only to override what is already defined in the task being copied.
**Note\:** existing criteria within a task are retained. For example, copying a task that contains `FileType` criteria and then adding `DateRange` criteria will result in a task that has both `FileType` and `DateRange`.
### taskType = Relocate
If `parentConfigId` and `taskNum` values are *not* specified (i.e. a new task is being created), then a `SmartMover` object must follow.
However, if `parentConfigId` and `taskNum` *are* specified, then no additional fields are required if the Relocate task is to be used ''as is''.
See the GET configurations call for a definition of the objects within a task.'
operationId: createConfiguration
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/createConfigurationRequest'
examples:
from_existing_task:
summary: Create a configuration based on an existing Configuration and its Task.
value:
baseConfigId: -1
newConfigName: some config name
description: new description
category: optional
tasks:
- parentConfigId: 101
taskNum: 0
taskType: Collect
label: new Label
responses:
'200':
description: Configuration was created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/createConfigurationResponse'
example:
id: 116
name: some config name
description: new description
template: Default
category: optional
targets: []
hasInputs: true
tasks:
- taskNum: 0
taskType: Collect
impersonation: None
label: new Label
Evidence:
destination: c:\collection
credentials: false
createFileSafe: true
compression: High
segmentSize: 2
segmentSizeUnit: GB
validateCollection: true
FileType:
analyzeSignatures: false
mode: Include
extensions:
- extension: contact
collectAll: false
- extension: dbx
collectAll: false
- extension: eml
collectAll: false
- extension: group
collectAll: false
- extension: idx
collectAll: false
- extension: MailDB
collectAll: false
- extension: mbx
collectAll: false
- extension: msf
collectAll: false
- extension: msg
collectAll: false
- extension: msmessagestore
collectAll: false
- extension: ns2
collectAll: false
- extension: ns3
collectAll: false
- extension: ns4
collectAll: false
- extension: nsf
collectAll: false
- extension: nws
collectAll: false
- extension: oeaccount
collectAll: false
- extension: ost
collectAll: false
- extension: pbx
collectAll: false
- extension: pst
collectAll: false
- extension: slt
collectAll: false
- extension: snm
collectAll: false
- extension: wab
collectAll: false
'400':
description: No JSON body, config field missing, no new tasks, name is missing etc.
content:
application/json:
schema:
$ref: '#/components/schemas/standardResponse'
example:
code: 400
id: 101
message: Invalid Configuration ID supplied
/v2/configurations/{id}:
delete:
tags:
- Collection Configuration
summary: Delete the Configuration
description: Delete the configuration identified by `{id}`
operationId: deleteConfiguration
parameters:
- name: id
in: path
description: Collection Configuration id
required: true
schema:
type: integer
responses:
'200':
description: Case was deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/standardResponse'
example:
code: 200
id: 101
message: OK
'400':
description: Configuration {id} could not be deleted
content:
application/json:
schema:
$ref: '#/components/schemas/standardResponse'
example:
code: 400
id: 101
message: Configuration {id} could not be deleted
'504':
description: Waiting for the model to load
content:
application/json:
schema:
$ref: '#/components/schemas/standardResponse'
example:
code: 504
id: 101
message: Waiting for the model to load
components:
schemas:
standardResponse:
type: object
properties:
code:
type: integer
description: http response status code
id:
type: integer
description: id of the affected Object
message:
type: string
description: http status message
Hash:
type: object
properties:
hashValue:
type: string
description: 32-character MD5 hash value
fileSize:
type: number
description: 'Optional file size.
If provided, will be used to match before calculating hash'
microHash:
type: string
description: 'Optional MD5 hash value of the first 64 KB of a file.
Used to match before calculating a full hash'
createConfigurationResponse:
type: object
properties:
id:
type: integer
description: id of the new Collection Configuration
name:
type: string
description: name of the new Collection Configuration
description:
type: string
description: description of the new Collection Configuration
template:
type: string
description: template of the new Collection Configuration
category:
type: string
description: Optional category of the new Collection Configuration
targets:
type: array
description: Array of targets specified in this Collection Configuration
items:
$ref: '#/components/schemas/Target'
hasInputs:
type: boolean
description: whether any input paths are specified within any of the Targets or Computers in this Collection Configuration
tasks:
type: array
description: Array of tasks specified in this Collection Configuration
items:
$ref: '#/components/schemas/TaskCreated'
Configuration:
type: object
properties:
id:
type: integer
description: id of the collection configuration
name:
type: string
description: name of the collection configuration
description:
type: string
description: description of the collection configuration
nullable: true
template:
type: string
description: name of the Template used by the collection configuration
nullable: true
category:
type: string
description: name of the Category (optional value attached to a collection configuration)
nullable: true
targets:
type: array
description: array of Target IDs used in this collection configuration
items:
type: integer
description: Target ID
nullable: true
computers:
type: array
description: array of Computer GUIDs used in this collection configuration
items:
type: string
description: computer GUID
nullable: true
hasInputs:
type: boolean
description: true if any input paths exist within the targets or computers specified in this collection configuration
tasks:
type: array
description: array of Tasks used in this collection configuration
items:
$ref: '#/components/schemas/Task'
FileType:
type: object
description: describes the file type filters used in the collection (this object is optional)
properties:
analyzeSignatures:
type: boolean
description: when `true`, read the beginning of each file to determine file type. When `false` use filename extension only to determine file type.
mode:
type: string
description: One of `Include` or `Exclude` - include or exclude the file types listed in the `extensions` array
enum:
- Include
- Exclude
extensions:
type: array
description: array of one or more file type extensions
items:
$ref: '#/components/schemas/Extension'
Evidence:
type: object
properties:
destination:
type: string
description: destination where evidence is to be saved
credentials:
type: boolean
description: Set to `true` if credentials are supplied to access the destination
createFileSafe:
type: boolean
description: Set to `true` to create a FileSafe, `false` save native copies of the files
compression:
type: string
description: Compression setting for saved data. One of `None`, `Medium`, `High` (used only if createFileSafe = `true`)
enum:
- None
- Medium
- High
segmentSize:
type: integer
description: size of each FileSafe segment (used only if createFileSafe = `true`)
segmentSizeUnit:
type: string
description: unit of measure which applies to segmentSize. One of `KB`, `MB`, or `GB` (used only if createFileSafe = `true`)
enum:
- KB
- MB
- GB
overwrite:
type: boolean
description: whether to overwrite existing files at the destination (used only if createFileSafe = `false`)
maintainFullPath:
type: boolean
description: whether to maintain the full path of the file at the destination (used only if createFieSafe = false)
validateCollection:
type: boolean
description: whether to validate the entire FileSafe after collection is completed
TaskCreated:
type: object
properties:
parentConfigId:
type: integer
description: Optional, id of the parent Collection Configuration of the new task to be copied. If omitted, the task is created from given params.
taskNum:
type: integer
description: Optional, id of the task to be copied (within the parent conf specified above). Required if parentConfigId is specified.
taskType:
type: string
description: 'Type of task\: one of `Collect`, `Relocate`, `Deploy`, or `Launch` (currently only `Collect` and `Relocate` are supported). NOTE\: If copying an Existing task, the `taskType` cannot be changed in the new task.'
enum:
- Collect
- Relocate
- Deploy
- Launch
label:
type: string
description: 'Optional, user-defined label for this job.
Can be used as search criteria for jobs.'
Task:
type: object
properties:
taskNum:
type: integer
description: 0-based index of tasks (jobs) to be run in this collection configuration
label:
type: string
description: 'user-defined label for this job.
Can be used as search criteria for jobs'
impersonation:
type: string
description: The enumeration value `None` or `Logged on User`
enum:
- None
- Logged on User
taskType:
type: string
description: 'The type of task. One of `Collect`, `Relocate`, `Deploy` or `Launch`.
This value will determine which fields follow.'
enum:
- Collect
- Relocate
- Deploy
- Launch
Evidence:
$ref: '#/components/schemas/Evidence'
FileType:
$ref: '#/components/schemas/FileType'
DateRange:
type: object
properties:
dates:
type: array
description: array of one or more date criteria
items:
$ref: '#/components/schemas/DateCriteria'
AdvancedSearch:
type: object
properties:
keywords:
type: array
description: array of keywords
items:
$ref: '#/components/schemas/Keyword'
Hash:
type: object
properties:
hashType:
type: string
description: always `MD5`
enum:
- MD5
hashes:
type: array
description: array of hash values used to identify files to be collected
items:
$ref: '#/components/schemas/Hash'
Volatile:
type: object
description: Describes a volatile configuration
properties:
collectVolatile:
type: boolean
description: Whether to collect volatile information, When `false` the remaining fields are ignored
collectHandles:
type: boolean
description: Whether to collect handles as part of the collection (collectVolatile must be `true`)
collectionScreenShots:
type: boolean
description: Whether to capture screen shots of all windows (requires impersonation, collectVolatile must be `true`)
screenShotFormat:
type: string
description: The graphic file format to save screen shot images. One of `PNG` or `JPG` (collectScreenShots must be `true`)
enum:
- PNG
- JPG
RAM:
type: object
description: Describes RAM collection
properties:
collectRAM:
type: boolean
description: When `true` saves a bit-for-bit image of the RAM
SmartMover:
type: object
description: For a `Deploy` or `Relocate` task. Specifies the copying or moving of files from one ECC Client to another
properties:
destinationFolder:
type: string
description: folder on the destination computer where evidence is to be copied
destComputerName:
type: string
description: name of the destination computer
destComputerId:
type: string
description: GUID of the destination computer
moveOrCopy:
type: string
description: '`Move` or `Copy`.
Either setting will copy files to the destination computer. `Move` will delete evidence from the source after the copy is complete.'
enum:
- Move
- Copy
relocateData:
type: boolean
description: When `true` relocate the evidence (data files)
relocateLogs:
type: boolean
description: When `true` relocate the collection logs
TargetInputs:
type: object
properties:
types:
type: string
description: Path, Local Path, or AutoDetect
enum:
- Path
- Local Path
- AutoDetect
location:
type: string
description: full path or AutoDetect setting for the source
exclusion:
type: string
description: excluded subfolders in the location (only for Path type)
TaskToCreate:
type: object
properties:
parentConfigId:
type: integer
description: optional, id of the parent Collection Configuration which holds the task to be copied. If omitted, the task is created from given parameters.
taskNum:
type: integer
description: optional, id of the task to be copied (within the parent conf specified above). Required if `parentConfigId` is specified.
taskType:
type: string
description: 'type of task\: one of `Collect`, `Relocate`, `Deploy`, or `Launch` (currently only `Collect` and `Relocate` are supported).
**Note\:** If copying an existing task, the `taskType` cannot be changed in the new task.'
enum:
- Collect
- Relocate
- Deploy
- Launch
label:
type: string
description: 'optional, user-defined label for this job.
Can be used as search criteria for jobs'
impersonation:
type: string
description: None or Logged on User
enum:
- None
- Logged on User
Evidence:
$ref: '#/components/schemas/Evidence'
FileType:
$ref: '#/components/schemas/FileType'
DateRange:
type: object
properties:
dates:
type: array
description: array of one or more date criteria
items:
$ref: '#/components/schemas/DateCriteria'
AdvancedSearch:
type: object
properties:
keywords:
type: array
description: array of keywords
items:
$ref: '#/components/schemas/Keyword'
Hash:
type: object
properties:
hashType:
type: string
description: always MD5
enum:
- MD5
hashes:
type: array
description: array of hashes
items:
$ref: '#/components/schemas/Hash'
Volatile:
type: object
description: Describes a volatile configuration
properties:
collectVolatile:
type: boolean
description: Whether to collect volatile information, When `false` the remaining fields are ignored
collectHandles:
type: boolean
description: Whether to collect handles as part of the collection (collectVolatile must be `true`)
collectionScreenShots:
type: boolean
description: Whether to capture screen shots of all windows (requires impersonation, collectVolatile must be `true`)
screenShotFormat:
type: string
description: The graphic file format to save screen shot images. One of `PNG` or `JPG` (collectScreenShots must be `true`)
enum:
- PNG
- JPG
RAM:
type: object
description: Describes RAM collection
properties:
collectRAM:
type: boolean
description: When `true` saves a bit-for-bit image of the RAM
SmartMover:
type: object
description: For a `Deploy` or `Relocate` task. Specifies the copying or moving of files from one ECC Client to another
properties:
destinationFolder:
type: string
description: folder on the destination computer where evidence is to be copied
destComputerName:
type: string
description: name of the destination computer
destComputerId:
type: string
description: GUID of the destination computer
moveOrCopy:
type: string
description: 'Move or Copy.
Move to delete evidence from the source after the copy is complete'
enum:
- Move
- Copy
relocateData:
type: boolean
description: true to relocate the evidence (data)
relocateLogs:
type: boolean
description: true to relocate the logs
Target:
type: object
properties:
id:
type: integer
description: id of the Target
name:
type: string
description: name of the target
description:
type: string
description: description of the target
custodianId:
type: integer
description: id of the Custodian this target belongs to
computerName:
type: string
description: name of the Computer this target belongs to
computerGUID:
type: string
description: GUID of the Computer this target belongs to
Inputs:
type: array
description: array of inputs in the target
items:
$ref: '#/components/schemas/TargetInputs'
Extension:
type: object
description: Describes a File Extension
properties:
extension:
type: string
description: file type extension (do not include the preceding dot)
collectAll:
type: boolean
description: If `true`, collect this file type regardless of keyword search
Keyword:
type: object
properties:
expressionName:
type: string
description: human-readable description of the search expression
expression:
type: string
description: search expression
caseSensitive:
type: boolean
description: When `true` specifies the search should be case-sensitive
regExpression:
type: boolean
description: When `true` specifies the `expression` is interpreted as a Regular Expression
listConfigurationsResponse:
type: object
properties:
configurations:
type: array
items:
$ref: '#/components/schemas/Configuration'
createConfigurationRequest:
type: object
properties:
baseConfigId:
type: integer
description: Id of an existing Collection Configuration to use as the basis for a new Collection Configuration, or -1 to create a new Collection Configuration from scratch
newConfigName:
type: string
description: New Collection Configuration name
description:
type: string
description: New Collection Configuration description
category:
type: string
description: Optional. A Category associated with this Collection Configuration (a GET call can filter by Category)
tasks:
type: array
description: Array of new tasks to add to the new collection configuration. At least one task must be specified.
items:
$ref: '#/components/schemas/TaskToCreate'
DateCriteria:
type: object
properties:
type:
type: string
description: 'One of `From` or `Last`.
`From` specifies absolute start/end dates.
`Last` specifies last number of days back from the current date'
enum:
- From
- Last
useGMT:
type: boolean
description: '`true` specifies GMT for time, `false` specifies local time'
startDate:
type: string
description: inclusive start date in the format `yyyy-mm-ddThh:mm:ss` (only used if type = `From`)
endDate:
type: string
description: inclusive end date in the format `yyyy-mm-ddThh:mm:ss` (only used if type = `From`)
numDays:
type: integer
description: number of days back from the current date (only used if type = `Last`)
checkCreation:
type: boolean
description: When `true`, apply date criteria to creation date
checkModification:
type: boolean
description: When `true` apply date criteria to modification date
checkAccess:
type: boolean
description: When `true`, apply date criteria to access date
securitySchemes:
BasicAuth:
type: http
scheme: basic