Using the CLI

netofuse is a shell script that constructs a docker run command to execute commands in the container image if you are using the container deployment and have run the Docker host setup script.

netofuse is the Python code directly running on your local system if you installed the Python package.

The commands work in the same way regardless of which deployment option you used. Remember that if you are using the container, all file paths refer to the path inside the container, not on your Docker host.

Commands

run

Usage: netofuse run [module]

Executes integration with the name specified and exits.

upload

Usage: netofuse upload [--transform FILE] [--neto API] [--use-labels] filename

Upload context labels to Netography Fusion in a supported file format (CSV or JSON) from a local file.

There are two different formats for CSV files that are supported for upload:

Upload a Generic CSV

The upload command by default expects generic output in csv format that will then have field names converted with the transform file specified.

📘

When to use a generic CSV format

This is useful if you have another application that is saving a CSV file to disk, as netofuse can handle transforming the names and values of the CSV with the transform, converting it to the Netography labels format, and upload it via API, handling all the cases of proper formatting, characters, and pagination for you.

It is also useful if you want to use a module to download the CSV file and then later upload it in a separate step to Netography. You might do this if you wanted to inspect or do post-processing on the CSV file before you upload context labels to Netograpy.

1. Create a transform file based on the headers using the buildtransform command with the -csv filename option.
2. Edit the transform file to create the desired field mappings. Consult Context Transforms for more details on this step.
3. Add the --transform filename option to the upload command to use this field mapping.

Example for generic CSV upload

mydata.csv

NAME,LOCATION,IP
myhost,Annapolis,10.0.0.1
yourhost,Atlanta,10.8.0.1

netofuse buildtransform --csv mydata.csv mydata.transform
nano mydata.transform  # or your preferred text/YAML editor
netofuse upload --transform mydata.transform mydata.csv

Directory to use with Docker

The default docker run script sets the working directory within the docker container to /app/netofuse/data and maps that to /var/netofuse on the Docker host. Place the CSV file in /var/netofuse and edit the transform in that directory, as netofuse within the container will not be able to access or write files in your local working directory.

Upload a Netography formatted context label CSV file

If the CSV file is already formatted as the Netography context labels API expects, it can be directly uploaded without any transform or further processing. This is also the format exported when you setlabels: csv in the save:section of a module configuration file.

📘

Netography context labels CSV format

The format of a labels CSV file is a file with no header row, with each row in the format of:

IP address, context name, value1, [value2], [value3], ...

The file should never have more than 1 row with the same IP address and context name. Instead, those values should all be appended to the single row. The values in a single row should never be duplicated.

To upload a CSV file in this format, add the --use-labelsargument.

required argument: filename

The file(s) to import - can specify as a full path, directory, or use wildcards

optional argument: [--transform FILE]

Transform file to use (default: netofuse.upload.transform).

optional argument: [--neto API]

Netography API to use (only needed if multiple APIs configured). This should be the name of the API section in the configuration file.

optional argument: [--use-labels]

If this option is set, the file specified must be in the Netography context label file format. This is the same format that is output when the labels key is set in thesave: section of the configuration. If this is not set, the file is transformed and converted to Netography context labels before uploading.

auth

Usage: netofuse auth [module/api]

Attempt to authenticate to API endpoints

Use this to test if the API configuration parameters and credentials you have set for the Netography API and the modules you have configured are successfully authenticating.

verify

Usage: netofuse verify [module]

Verify that the module is properly configured, authentication is working, and that asset information is being successfully retrieved. Testing any new or changed configurations for a module with this command is good practice. Verify will not upload any context labels to Netography Fusion, even if upload:true is set or -u is used.

optional argument: [module]

If specified, the module will be tested.
If not specified, only the Netography API will be verified.

clear

Usage: clear [module]

Clears the cache (including both any asset data and authentication tokens)

optional argument: [module]

If specified, only asset data from this module instance will be cleared.
If not specified, all asset data will be cleared.

init

Usage: init [--force] [--envfile][filename]

Initializes a new default configuration file and saves it as a file.

optional argument: [--force]

If this option is set, an existing configuration file will be overwritten if it exists.

optional argument:[--envfile]

If specified, the configuration will be written to an environment file instead of a yml file.

optional argument:[filename]

If specified, write the default configuration to this file.
If not specified, netofuse.yml in the current directory is used by default, unless --envfile is also set, in which case .netofuse.env is used by default.
Configuration is written to the current directory, unless a full path is specified, or the --dir command line option has set a new directory.

buildtransform

Usage: buildtransform [--force] [--csv filename] [module] [filename]

Builds a new transform configuration by running an existing module or reading from a local CSV file. This is useful if you have configured a module to gather a new set of fields, as this will run the module to identify what fields are being returned, gather an example of values that can be used, and then create the structure for the transform that you can then modify to map fields and modify values. For more details on how transforms work, see Context Transforms.

optional argument: [--force]

If this option is set, force overwriting an existing transform configuration, even if it already exists.

optional argument: [--csv filename]

If this option is set and filename is specified, a CSV file (with a header row) will be read and used to build the transform configuration.

required argument: [module]

The name of the module instance to run to build a transform for. This must be specified unless the --csv option is used.

optional argument: [filename]

The name of the file to write the transform configuration that is built by this command. If not specified, it will write to transform.ymlby default.

api

Usage: api [--file filename] [--neto api] [--bytes N] method command [params *]

You can directly interact with the Netography Fusion API from the NetoFuse command line with the api command. See API Reference for more details of what is available in the API. Not all API calls are compatible with this command currently, but many are.

required argument: method

HTTP method to use in making API call (default: GET)

required argument: command

API command to execute (eg labels/ips/10.1.1.1)

optional argument: [params *]

List of parameters to set when making this cal (format is key=value)

optional argument: [--file filename]

Write the API response to a file (default is to STDOUT)

optional argument: [--neto api]

Netography API to use (only needed if multiple APIs configured). This should be the name of the API section in the configuration file (api1 by default)

optional argument: [--bytes N]

Number of bytes to display from the API response (default: all)

delete-labels

Usage: delete-labels api

Delete all context labels from the Netography Fusion API instance specified.

required argument: api

This can be useful if you have been testing a new module and need to reset the labels available in your account. Although most context labels are built using integrations that will automatically repopulate them, use caution deleting labels from your account if you have manually imported labels or have other context labels that are being used actively in production.

additional commands

There are additional commands that may be listed by using the --help command. These may be infrequently used or to be deprecated commands. Use caution when running commands that are not fully documented, and contact Netography Support if you have any questions.

Command Line Options

-h, --help

Provides command line usage help

-c FILE, --config FILE

Specifies the location of the YAML configuration file to be used. By default, it uses netofuse.yml in the current directory if this is not set.

-e FILE, --env FILE

Specifies the location of the environment file to be used. By default, it uses .netofuse.env in the current directory if this is not set.

-d DIRECTORY, --dir DIRECTORY

Specifies the working directory netofuse uses to read and write files from. Full pathnames specified will take precedence over the working directory for any files used.

-r, --resetcache

Clears the cache before executing a command.

-n, --nocache

Disables caching. This overrides any configuration file settings.

-u, --upload

Enables uploading of labels to the configured Netography API with the command. This overrides upload: false being set in configuration.

-x, --noupload

Disables uploading of labels. This overrides upload: true being set in configuration.

-l LEVEL, --level LEVEL

Sets the logging level. Available logging levels are INFO, VERBOSE, WARNING, ERROR, DEBUG, TRACE.

-t FILE, --allow-custom-transforms FILE

Enables custom transform functions in the specified Python file. See Context Transforms for more details on how to use this option.

-v, --version

Prints the NetoFuse version and exits.