Getting started

New to Nuclei in Python? Don’t worry, you’ve found the perfect place to get started!

Full documentation of the Nuclei APIs can be found by logging in to on the nuclei website.

If you don’t yet have a Nuclei account you can create one for free(!) from the Sign Up tab after clicking Log In on the nuclei website.

Installation

To install this package, including the NucleiClient library and its dependencies, run:

pip install cems-nuclei[client]

To skip the installation of the NucleiClient library, in case you do not need it (e.g. only use pure requests), run:

pip install cems-nuclei

User Token

To connect to Nuclei you’ll first need a user token. You can obtain this token by signing in to the nuclei website and navigate to the API Access Tokens section. Here you can create new tokens and copy the User Token.

It is recommended to store this token as the environmental variable NUCLEI_TOKEN in your Python environment. Else you will be prompted for this token when necessary.

Guided usage

If you’re not so comfortable with creating your own API calls, you can easily access the nuclei endpoints by creating a NucleiClient object and using the call_endpoint() to handle the calls for you.

For instance, calling the healthcheck endpoint of the VibraCore application can be done as such:

In [1]: from nuclei.client import NucleiClient

In [2]: client = NucleiClient()

In [3]: client.call_endpoint(
   ...:     app="VibraCore",
   ...:     endpoint="/healthcheck",
   ...: )
   ...: 
Out[3]: 'server alive'

call_endpoint() automatically returns the unpacked response object. You can get the raw response by setting the return_response argument to True.

If the endpoint requires a schema, it can be passed as a Python dictionary to the schema argument of call_endpoint(). The schema is automatically parsed with the serialize_jsonifyable_object() function (see below) so in most cases you won’t have to worry about passing the correct types.

The NucleiClient can provide you with a list of Nuclei applications:

In [4]: print(client.applications)
['PileCore', 'VibraCore', 'CPT Core', 'ShallowCore']

And can also fetch the available versions for an application for you:

In [5]: versions = print(client.get_versions(app="PileCore"))
['v2', 'v3', 'latest']

And can also fetch the available endpoints for an application for you:

In [6]: endpoints = print(client.get_endpoints(app="PileCore", version="latest"))
['/healthcheck', '/compression/single-cpt/plot-bearing-capacity', '/compression/single-cpt/results', '/compression/single-cpt/report', '/grouper/generate_grouper_report', '/get-task-result', '/get-task-status', '/compression/multiple-cpts/results', '/compression/multiple-cpts/plot-bearing-capacity', '/compression/multiple-cpts/report', '/pile_properties/shape', '/pile_properties/type', '/friction-ranges/lower-bound', '/grouper/group_cpts', '/grouper/optimize_groups', '/grouper/group_metrics']

You can also check the applications to which you have full access:

In [7]: permissions = print(client.user_permissions)
['read:cptcore+classify', 'read:cptcore+parse', 'read:latex+report', 'read:pilecore+calculate', 'read:pilecore+report', 'read:shallowcore+calculate', 'read:shallowcore+report', 'read:vibracore+calculate', 'read:vibracore+report']

If an application is not listed here, your usage of the app is limited. Check the documentation of the specific apps to see the limitations.

Advanced usage

If you want to have full control and create your own API calls with the requests package, you can do so by calling create_session().

In [8]: import nuclei

In [9]: nuclei.create_session()
Out[9]: <requests.sessions.Session at 0x7f37e7b112b0>

This will return a requests.Session object with a response hook that covers authentication for you.

Schema serialization

The automatic schema serialization tools are also available to advanced users by calling the serialize_jsonifyable_object() function directly.

The following code-block shows the mechanism behind these functions. First we create a numpy.array and transforms it to a serialized list with serialize_jsonifyable_object().

In [10]: import numpy as np

In [11]: from nuclei.client import utils

In [12]: schema = np.array([[np.int16(1), 2.0], [np.nan, np.float32(4)]])

In [13]: message = utils.serialize_jsonifyable_object(schema)

In [14]: print(message)
[[1.0, 2.0], [None, 4.0]]