Nuix SDK – User Scripts

Getting Started: Introduction

Mon, 11 Jan 2021 00:00:00 +0000

SUPPORTED LANGUAGES

Ruby
JavaScript
Python

CONFIGURATION

There are two ways to execute user scripts. They can either be submitted directly as a string to the /userScripts or /cases/{caseId}/userScripts endpoints in the script field, or you can place your script in a file in the user scripts directory and invoke them from the same endpoints by specifying the script name in the fileName field.

The user scripts directory is configurable and can be set in the application.properties file.

userScriptsLocation="/Path/To/UserScripts/Directory"

VARIABLES

Each script has several common local variables injected, all of which are available both with and without a leading dollar sign ($):

current_case (also as currentCase):This is the Java nuix.Case object. It is only available in the case-specific endpoint /cases/{caseId}/userScripts.
utilities: This is the Java nuix.Utilities object for the current environment.
request: This is the Java HttpServletRequest object.
response: This provides methods for customising the object that is returned from the server. These methods are:
- setStatus(int httpStatusCode): This sets the HTTP status code.
- addHeader(String headerName, String headerValue): This adds a header to the actual HTTP response that comes back from the server.
- setBody(Object body): This sets the payload of the response.
progress : This provides methods for updating the progress of the script when run in an asynchronous manner. These methods are:
- setStatus(String status): This sets an arbitrary status value. This will be reflected in the ‘‘status’’ variable in the AsyncFunctionStatus response.
- setEstimatedFinalValue(long value)): This sets an estimate for the final progress value. This will be reflected in the ‘‘total’’ variable in the AsyncFunctionStatus response, and will be used as the denominator when calculating percent complete.
- setCurrentValue(long value): This sets the current progress value. This will be reflected in the ‘‘progress’’ variable in the AsyncFunctionStatus response, and will be used as the numerator when calculating percent complete.
custom_arguments (also as customArguments): This is the map of provided custom arguments.

Getting Started: Elasticsearch Case Subset

Mon, 13 Jan 2020 00:00:00 +0000

Example Scripts

class ElasticsearchCaseSubset
  def initialize(exportPath, query)
        @exportPath = exportPath
        @query = query
        @out = Hash.new
        @exceptions = Array.new
  end

  def process
    begin
      items = $current_case.search(@query);
      @out[:item_count] = items.size();
      @out[:exportPath] = @exportPath
      options = {
        "evidenceStoreCount" => 1,
        "includeFamilies" => false,
        "copyTags" => false,
        "copyComments" => false,
        "copyCustodians" => false,
        "copyItemSets" => false,
        "copyClassifiers" => false,
        "copyMarkupSets" => false,
        "copyProductionSets" => false,
        "copyClusters" => false,
        "copyCustomMetadata" => false,
        "caseMetadata" => {
          "name" => "ESCaseSubset",
          "description" => "About My simple Case",
          "investigator" => "Inspector Gadget",
          "elasticSearchSettings" => {
            "index.refresh_interval" => "60s",
            "nuix.transport.hosts" => "127.0.0.1:9300",
            "cluster.name" => "elasticsearch",
            "index.number_of_replicas" => "0",
            "nuix.index.auto_close" => "false",
            "index.number_of_shards" => "5",
            "xpack.security.transport.ssl.enabled" => "false"
            }
        }
      }
      @out[:started] = Time.now.strftime('%Y-%m-%d_%H-%M-%S')
      $utilities.getCaseSubsetExporter().exportItems(items, @exportPath, options);
    rescue => exception
       @exceptions << {:class => exception.class.name, :message => exception.message}
    end
    @out[:exceptions] = @exceptions
    @out[:finished] = Time.now.strftime('%Y-%m-%d_%H-%M-%S')
    return @out
  end
end
$response.setBody(ElasticsearchCaseSubset.new("/Cases/ESCaseSubsetUserScript", "file-extension:html").process)

function ElasticsearchCaseSubset(exportPath, query) {
  this.exportPath = exportPath;
  this.query = query;
}

ElasticsearchCaseSubset.prototype.process = function() {
  var out = {};
  try {
    var items = current_case.search(this.query);
    out['item_count'] = items.length;
    out['exportPath'] = this.exportPath;

    var options = {};
    options['evidenceStoreCount'] = 1;
    options['includeFamilies'] = false;
    options['copyTags'] = false;
    options['copyComments'] = false;
    options['copyCustodians'] = false;
    options['copyItemSets'] = false;
    options['copyClassifiers'] = false;
    options['copyMarkupSets'] = false;
    options['copyProductionSets'] = false;
    options['copyClusters'] = false;
    options['copyCustomMetadata'] = false;

    var elasticSearchSettings = {};
    elasticSearchSettings['index.refresh_interval'] = '60s';
    elasticSearchSettings['nuix.transport.hosts'] = '127.0.0.1:9300';
    elasticSearchSettings['cluster.name'] = 'elasticsearch';
    elasticSearchSettings['index.number_of_replicas'] = '0';
    elasticSearchSettings['nuix.index.auto_close'] = 'false';
    elasticSearchSettings['index.number_of_shards'] = '5';
    elasticSearchSettings['xpack.security.transport.ssl.enabled'] = 'false';

    var caseMetadata = {};
    caseMetadata['name'] = 'ESCaseSubset';
    caseMetadata['description'] = 'About my simple case.';
    caseMetadata['investigator'] = 'Inspector Gadget';
    caseMetadata['elasticSearchSettings'] = elasticSearchSettings;

    options['caseMetadata'] = caseMetadata;

    out['started'] = new Date().getTime().toString();
    utilities.getCaseSubsetExporter().exportItems(items, this.exportPath, options);
  } catch(err) {
    out['exceptions'] = err.message;
  }
  out['finished'] = new Date().getTime().toString();
  return out;
}

$response.setBody(new ElasticsearchCaseSubset("/Cases/ESCaseSubsetUserScript", "file-extension:html").process())

import time

class ElasticsearchCaseSubset: 

  def __init__(self, exportPath, query): 
    self.exportPath = exportPath 
    self.query = query
    self.out = {}
    self.exceptions = []

  def process(self):
    try:
      items = current_case.search(self.query);
      self.out['item_count'] = len(items)    
      self.out['exportPath'] = self.exportPath

      options = {
        "evidenceStoreCount": 1,
        "includeFamilies": False,
        "copyTags": False,
        "copyComments": False,
        "copyCustodians": False,
        "copyItemSets": False,
        "copyClassifiers": False,
        "copyMarkupSets": False,
        "copyProductionSets": False,
        "copyClusters": False,
        "copyCustomMetadata": False,
        "caseMetadata": {
          "name": "ESCaseSubset",
          "description": "About My simple Case",
          "investigator": "Inspector Gadget",
          "elasticSearchSettings": {
            "index.refresh_interval": "60s",
            "nuix.transport.hosts": "127.0.0.1:9300",
            "cluster.name": "elasticsearch",
            "index.number_of_replicas": "0",
            "nuix.index.auto_close": "false",
            "index.number_of_shards": "5",
            "xpack.security.transport.ssl.enabled": "false"
          }
        }
      }
      self.out['started'] = int(round(time.time() * 1000))
      utilities.getCaseSubsetExporter().exportItems(items, self.exportPath, options);
    except Exception, e: 
      self.exceptions.append(str(e))

    self.out['finished'] = int(round(time.time() * 1000))
    return self.out

processor = ElasticsearchCaseSubset("/Cases/ESCaseSubsetUserScript", "file-extension:html")
response.setBody(processor.process())

Example Request

curl --location --request PUT 'http://localhost:8080/nuix-restful-service/svc/v1/cases/ab490af89d29460db0011f105ce6a340/userScripts' \
--header 'nuix-auth-token: YOUR_AUTH_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "fileName": "ElasticsearchCaseSubset.rb",
  "language": "RUBY",
  "async": false
}'

wget --no-check-certificate --quiet \
  --method PUT \
  --timeout=0 \
  --header 'nuix-auth-token: YOUR_AUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --body-data '{
  "fileName": "ElasticsearchCaseSubset.rb",
  "language": "RUBY",
  "async": false
}' \
   'http://localhost:8080/nuix-restful-service/svc/v1/cases/ab490af89d29460db0011f105ce6a340/userScripts'

Getting Started: Tagging

Sun, 12 Jan 2020 00:00:00 +0000

Example Scripts

query="file-extension:pdf"
items=$current_case.searchUnsorted(query)

items.each do |item|
    item.addTag("pdf")
end

response.setBody(items.length())

query="file-extension:pdf"
items=current_case.searchUnsorted(query)

for (item in items) {
    item.addTag("pdf");
}

response.setBody(items.length)

query="file-extension:pdf"
items=current_case.searchUnsorted(query)

for item in items:
    item.addTag("pdf")
    
response.setBody(len(items))

Example Request

curl --location --request PUT 'http://localhost:8080/nuix-restful-service/svc/v1/cases/{caseId}/userScripts' \
--header 'nuix-auth-token: YOUR_AUTH_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "fileName": "tagItems.rb",
  "language": "RUBY",
  "async": false
}'

wget --no-check-certificate --quiet \
  --method PUT \
  --timeout=0 \
  --header 'nuix-auth-token: YOUR_AUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --body-data '{
  "fileName": "tagItems.rb",
  "language": "RUBY",
  "async": false
}' \
   'http://localhost:8080/nuix-restful-service/svc/v1/cases/{caseId}/userScripts'

Getting Started: Custom Processing

Sun, 12 Jan 2020 00:00:00 +0000

class CustomProcessor
    def initialize(case_path, case_name, process_this)
        @case_path = case_path
        @case_name = case_name
        @process_this = process_this
        @out = Hash.new
        @items = Array.new
        @exceptions = Array.new
    end

    def process
        begin
            case_settings = {:compound => false, :name => "#{@case_name}", :description => "Simple Case", :investigator => "Inspector Gadget"}
            current_case = $utilities.caseFactory.create("/Cases/CustomProcessing", case_settings)
            processor = current_case.createProcessor()
            processor.processing_settings = {:report_processing_status => "physical_files",
                                             :enable_custom_processing => ["text", "properties", "binary"]
            }
            processor.parallel_processing_settings = {:worker_count => 2, :worker_memory => 2000 }
            processor.when_item_processed do | callback |
                begin
                    item = Hash.new
                    item[:mimetype] = callback.getMimeType()
                    unless callback.getBinaryFile().nil?
                        item[:path_to_binary] = callback.getBinaryFile().toString()
                    end
                    item[:properties] = callback.properties
                    item[:text] = callback.getText()
                    item[:path] = callback.path
                    @items << item
                rescue => exception
                   @exceptions << {:class => exception.class.name, :message => exception.message}
                end
            end
            container = processor.new_evidence_container("Evidence-#{Time.now.strftime('%Y-%m-%d_%H-%M-%S')}")
            container.addFile(@process_this)
            container.save
            @out[:processing_started] = Time.now.strftime('%Y-%m-%d_%H-%M-%S')
            processor.process
            @out[:final_item_count] = @items.length()
            current_case.close
        rescue => exception
           @exceptions << {:class => exception.class.name, :message => exception.message}
        end
        @out[:exceptions] = @exceptions
        @out[:items] = @items
        @out[:processing_finished] = Time.now.strftime('%Y-%m-%d_%H-%M-%S')
        return @out
    end
end
$response.setBody(CustomProcessor.new("/Cases", "CustomProcessing", "/Engines/9.0.0.171/doc/api").process)

function CustomProcessor(casePath, caseName, processThis) {
  this.casePath = casePath;
  this.caseName = caseName;
  this.processThis = processThis;
  this.items = [];
  this.exceptions = [];
  this.out = {};
}

CustomProcessor.prototype.process = function() {
  try {
    var caseSettings = {};
    caseSettings['compound'] = false;
    caseSettings['name'] = this.caseName;
    caseSettings['description'] = 'Simple Case';
    caseSettings['investigator'] = 'Inspector Gadget';

    var currentCase = utilities.getCaseFactory().create(this.casePath + '/' + this.caseName, caseSettings);
    var processor = currentCase.createProcessor();

    var processingSettings = {};
    processingSettings['report_processing_status'] = 'physical_files';
    processingSettings['enable_custom_processing'] = ["text", "properties", "binary"];

    var parallelProcessingSettings = {};
    parallelProcessingSettings['worker_count'] = 2;
    parallelProcessingSettings['worker_memory'] = 2000;

    processor.setProcessingSettings(processingSettings);
    processor.setParallelProcessingSettings(parallelProcessingSettings);

    var self = this;
    processor.whenItemProcessed(function(callback) {
      try {
        var item = {};
        item['mimtype'] = callback.getMimeType();

        if(callback.getBinaryFile()) {
          item['path_to_binary'] = callback.getBinaryFile().toString();
        }

        item['properties'] = callback.getProperties();
        item['text'] = callback.getText();
        item['path'] = callback.getPath();
        self.items.push(item);
      } catch (err) {
        self.exceptions.push(err.message);
      }
    });

    var startTime = new Date().getTime().toString();
    var container = processor.newEvidenceContainer('Evidence-' + startTime);
    container.addFile(this.processThis);
    container.save();
    this.out['processing_started'] = startTime;
    processor.process();
    this.out['final_item_count'] = this.items.length;
    currentCase.close();
  } catch (err) {
    this.exceptions.push(err.message);
  }
  this.out['exceptions'] = this.exceptions;
  this.out['items'] = this.items;
  this.out['processing_finished'] = new Date().getTime().toString();
  return this.out;
}

$response.setBody(new CustomProcessor("/Cases", "CustomProcessing", "/Engines/9.0.0.171/doc/api").process())

import time
import os

class CustomProcessor:

  def __init__(self, case_path, case_name, process_this):
    self.case_path = case_path
    self.case_name = case_name
    self.process_this = process_this
    self.out = {}
    self.exceptions = []
    self.items = []

  def when_item_processed(self, callback):
    try:
      item = {}
      item['mimetype'] = callback.getMimeType();

      if callback.getBinaryFile() is not None:
        item['path_to_binary'] = callback.getBinaryFile().toString()

      item['properties'] = callback.getProperties()
      item['text'] = callback.getText()
      item['path'] = callback.getPath()
      self.items.append(item)
    except Exception, e:
      self.exceptions.append(str(e))


  def process(self):
    try:
      case_settings = {"compound": False, "name": self.case_name, "description": "Simple Case", "investigator": "Inspector Gadget"}
      current_case = utilities.getCaseFactory().create(os.path.join(self.case_path, self.case_name), case_settings)
      processor = current_case.createProcessor()
      processing_settings = {"report_processing_status": "physical_files", "enable_custom_processing": ["text", "properties", "binary"]}
      parallel_processing_settings = {"worker_count": 2, "worker_memory": 2000}

      processor.setProcessingSettings(processing_settings)
      processor.setParallelProcessingSettings(parallel_processing_settings)
      processor.whenItemProcessed(self.when_item_processed)
      started = int(round(time.time() * 1000))
      container = processor.newEvidenceContainer("Evidence-" + str(started))
      container.addFile(self.process_this)
      container.save()
      self.out['processing_started'] = started
      processor.process()
      self.out['final_item_count'] = len(self.items)
      current_case.close()
    except Exception, e:
      self.exceptions.append(str(e))

    self.out['finished'] = int(round(time.time() * 1000))
    self.out['exceptions'] = self.exceptions
    self.out['items'] = self.items
    return self.out

processor = CustomProcessor("/Cases", "CustomProcessing", "/Engines/9.0.0.171/doc/api")
response.setBody(processor.process())

curl --location --request PUT 'http://localhost:8080/nuix-restful-service/svc/v1/userScripts' \
--header 'nuix-auth-token: YOUR_AUTH_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"async": false,
"fileName": "customProcessing.rb",
"language": "RUBY"
}
'

wget --no-check-certificate --quiet \
  --method PUT \
  --timeout=0 \
  --header 'nuix-auth-token: YOUR_AUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --body-data '{
  "async": false,
  "fileName": "customProcessing.rb",
  "language": "RUBY"
}
' \
   'http://localhost:8080/nuix-restful-service/svc/v1/userScripts'