ai.nightfall.scan

Class NightfallClient

java.lang.Object

ai.nightfall.scan.NightfallClient

All Implemented Interfaces:

Closeable, AutoCloseable

public class NightfallClient
extends Object
implements Closeable

Provides a client for accessing the Nightfall Developer Platform.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	NightfallClient.Builder A builder class that configures, validates, then creates instances of a Nightfall Client.

Method Summary

Modifier and Type	Method and Description
void	close() Closes this client and releases underlying system resources.
ScanFileResponse	scanFile(ScanFileRequest request, InputStream content, long contentSizeBytes) A convenience method that abstracts the details of the multi-step file upload and scan process.
ScanFileResponse	scanFile(ScanFileRequest request, InputStream content, long contentSizeBytes, Duration timeout) A convenience method that abstracts the details of the multi-step file upload and scan process.
ScanTextResponse	scanText(ScanTextRequest request) Scans the provided plaintext against the provided detectors, and returns all findings.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

close

public void close()

Closes this client and releases underlying system resources.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

scanText

public ScanTextResponse scanText(ScanTextRequest request)

Scans the provided plaintext against the provided detectors, and returns all findings. The response object will contain a list of lists representing the findings. Each index i in the findings array will correspond one-to-one with the input request payload list, so all findings stored in a given sub-list refer to matches that occurred in the ith index of the request payload.

Parameters:

request - the data to scan, along with the configuration describing how to scan the data. The request payload may not exceed 500KB.

Returns:

an object containing the findings from each item in the request payload

Throws:

NightfallAPIException - thrown if a non-2xx status code is returned by the API.

NightfallClientException - thrown if a I/O error occurs while processing the request

IllegalArgumentException - thrown if request is null

NightfallRequestTimeoutException - thrown if the request is aborted because the timeout is exceeded

scanFile

public ScanFileResponse scanFile(ScanFileRequest request,
                                 InputStream content,
                                 long contentSizeBytes)

A convenience method that abstracts the details of the multi-step file upload and scan process. In other words, calling this method for a given file is equivalent to (1) manually initializing a file upload session, (2) uploading all chunks of the file, (3) completing the upload, and (4) triggering a scan of the file.

The maximum allowed contentSizeBytes is dependent on the terms of your current Nightfall usage plan agreement; check the Nightfall dashboard for more details.

This method consumes the provided InputStream, but it *does not* close it; closing remains the caller's responsibility.

Parameters:

request - contains configuration describing which detectors to use to scan the file, as well as a webhook URL for delivering the results of the scan.

content - a stream of the bytes representing the file to upload

contentSizeBytes - the size of the input stream

Returns:

an acknowledgment that the asynchronous scan has been initiated.

Throws:

NightfallAPIException - thrown if a non-2xx status code is returned by the API.

NightfallClientException - thrown if a I/O error occurs while processing the request

NightfallRequestTimeoutException - thrown if the request is aborted because read/write timeout is exceeded

scanFile

public ScanFileResponse scanFile(ScanFileRequest request,
                                 InputStream content,
                                 long contentSizeBytes,
                                 Duration timeout)

A convenience method that abstracts the details of the multi-step file upload and scan process. In other words, calling this method for a given file is equivalent to (1) manually initializing a file upload session, (2) uploading all chunks of the file, (3) completing the upload, and (4) triggering a scan of the file.

The maximum allowed contentSizeBytes is dependent on the terms of your current Nightfall usage plan agreement; check the Nightfall dashboard for more details.

This method consumes the provided InputStream, but it *does not* close it; closing remains the caller's responsibility.

Parameters:

request - contains configuration describing which detectors to use to scan the file, as well as a webhook URL for delivering the results of the scan.

content - a stream of the bytes representing the file to upload

contentSizeBytes - the size of the input stream

timeout - the allowed duration for the request; if the execution time exceeds this duration, the request will be aborted.

Returns:

an acknowledgment that the asynchronous scan has been initiated.

Throws:

NightfallAPIException - thrown if a non-2xx status code is returned by the API.

NightfallClientException - thrown if a I/O error occurs while processing the request

NightfallRequestTimeoutException - thrown if execution time exceeds the provided timeout, or if an HTTP request is terminated by the client for exceeding read/write timeouts.