Extensions and the SDK

The SDK allows users to easily extend the capabilities of GUARDARA using Python. The SDK generates templates for different extension types that can be extended to implement a wide variety of capabilities. The generated SDK templates also include the documentation to guide users with the development.

The SDK can also be used to package the extension into a form that is uploadable to GUARDARA via the Settings > Inventory page.

Installing the SDK

To use the SDK, you will have to have Python 3.7 or 3.8 already installed.

The installation process is as simple as:

1. Download the SDK from the Settings > Developers page of the GUARDARA Manager.
2. Decompress the SDK archive
3. From the root directory of the extracted SDK run pip3 install .

Setting up the SDK

The SDK must be configured first to be able to develop extensions. This section discusses the different steps of setting up a GUARDARA development environment.

Generate Developer Key Pair

Each developer must have a unique private and public key pair because extension packages are cryptographically signed. Only extensions signed with a trusted key can be imported into the GUARDARA Inventory.

GUARDARA administrator(s) can register developers via the GUARDARA Manager using the developer’s public key. As of this, all developers must provide their public key to the administrator. Once registered, GUARDARA returns a Developer ID. The administrator should share this unique ID with the developer to configure the SDK.

To generate a suitable keypair, issue the commands below.

ssh-keygen -t rsa -b 4096 -m PEM

The above command will generate a public key and a private key. Please note:

• Only RSA keys in PEM format are supported
• Password/passphrase protected private keys are not supported

As the next step, the public key has to be converted into RSA PEM format using the command below.

ssh-keygen -e -m PEM -f ${PUB_KEY_PATH} > ${$PUB_KEY_PATH}.pem

The value of the ${$PUB_KEY_PATH} variable should point to the generated public key file.

Share the resulting public key with your GUARDARA administrator so he/she can register it.

Register Developer

The administrator can register developers via GUARDARA Manager under Settings > Development tab. To register a new developer, click on the + button and complete the form. Once the form is submitted, the returned Developer ID can be used to configure the SDK.

Configure the SDK

Issue the following command to start the process.

guardara configuration -c

During the configuration you will be prompted for the following information.

Information	Description
Full Name	The full name of the developer. This information is included in the manifest file of all generated extensions.
Email Address	The email address of the developer. This information is included in the manifest file of all generated extensions.
Developer ID	A developer ID is an identifier that uniquely identifies a developer. The GUARDARA Manager generates this ID during developer registration.
Public Key	The full path to the public key of the developer. This key is used to validate the cryptographic signature of packaged extensions.
Private Key	The full path to the private key of the developer. This key is used to sign packaged extensions cryptographically.

During configuration you will also be asked if you have API credentials. In case you do, you may want to provide them to the SDK. Having your API credentials configured:

• You will be able to easily fetch those when using the API module of the SDK
• You will be able to deploy your extensions using the SDK if your API key have the necessary permissions assigned

Using the SDK

The SDK allows users to easily extend the capabilities of GUARDARA using Python. It achieves this by generating templates for different extension types. These templates also include the documentation to guide users with the development.

GUARDARA operate with four extension types, these are: driver, monitor, primitive, and transform. The table below summarizes the different extension types and their purpose.

Please note, even though Primitives have been renamed to Fields across the user interface and the documentation, the SDK still refers to Fields as Primitives. This will change in a future release and the Engine and the SDK will adopt the “Field” name. 

Extension Type	Description
Primitive	Primitives (Fields) are the basic building blocks of any protocol or file templates. The fields of any structured data can be represented using primitives. The goal of a primitive is to represent a field of structured data and perform field-specific mutations.
Transform	Transforms are transformations that can be attached to individual primitives or a group of primitives. A transform modifies the mutated value of a primitive or group of primitives, and the result of the transformation will become the final value of the primitive or primitive group. An example of a transform could be Base64 encoding.
Driver	Drivers allow GUARDARA to communicate with the products to be tested. Some products communicate over the network, some over the air, and some work with files. With custom drivers, it is possible to extend the capabilities of GUARDARA to interact with almost any product.
Monitor	Monitors are extensions that allow GUARDARA to query the state of the targets being tested.

Creating an Extension

To generate an extension template using the SDK issue the command below. Make sure to replace <type> with the desired extension type.

guardara extension -e <type> -o create

You will find additional information on how to implement your desired extension in the README.md and DEVELOPMENT.mdfiles generated alongside the extension template files. In addition, the methods of each extension type to be implemented are documented within the source code generated.

Packaging Extensions

Once you have implemented your extension, it must be packaged to be able to upload it to the GUARDARA Inventory. To package your extension, issue the command below. Make sure to replace <type> with the desired extension type, and <name> with the name of your extension. The name of the extension is identical to the name of the directory the SDK generated your extension template under.

guardara extension -e <type> -o package -n <name>

Deploying Extensions

There are two ways to deploy packaged extensions:

If you have set up API access during the SDK configuration you can execute the below command to get your extension deployed to GUARDARA.

guardara extension -e <type> -o deploy -n <name>

Make sure to replace <type> with the extension type, and <name> with the name of your extension. The name of the extension is identical to the name of the directory the SDK generated your extension template under.

Alternatively, extension can be deployed manually. Go to the Settings > Inventory page to upload your packaged extension.

Extension External Dependencies

Extensions may depend on external libraries. These dependencies should be listed using the install_requires variable in the setup.py file of the backend component, so pip can download and install them at the time the extension is deployed.

An example can be seen below.

install_requires=[
    'uuid',
    'regex',
    'numpy'
]

Testing and Debugging Extensions

It is highly recommended to thoroughly test any custom extensions. Implement unit tests to ensure the code is working as expected. When using extensions with GUARDARA, should there be any issues detected with the extension at run time, an error message along with the stack trace becomes visible in the Activity Log section of the detailed test status page or on the Engine’s console.

More Information

You can find additional information on how to implement your extension in the README.md and DEVELOPMENT.mdfiles generated by the SDK alongside the extension template files. In addition, the methods of each extension type to be implemented are documented within the source code generated.