SDK
The SDK allows users to easily extend the capabilities of GUARDARA using Python. It achieves this by generating templates for different extension types.
The SDK is a Python module that contains everything needed to interact with GUARDARA in a programmatic way and to create extensions. The SDK can be downloaded from the Settings > Developers page of the GUARDARA Manager.
The SDK is made up of two parts, the SDK which enables developing GUARDARA extensions, and the API to interact with GUARDARA using it's API.
Setting up 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.
The SDK is a Python module that contains everything needed to interact with GUARDARA in a programmatic way and to create extensions. The SDK can be downloaded from the Settings > Developers page of the GUARDARA Manager.
The SDK is made up of two parts, the SDK which enables developing GUARDARA extensions, and the API to interact with GUARDARA using it's API.
Installation
The SDK can be installer as any reguar Python module. You will need at least Python 3.8 and pip installed. Assuming you are in the root folder of the SDK, the installation is as simple as:
pip3 install .
Please note, you may have to install the pycrypto module manually depending on your operating system:
pip3 install pycrypto
Setup
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 by a trusted developer can be imported into the GUARDARA Inventory.
GUARDARA administrators can register developers via the 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.
Registering a Developer
The administrator can register developers via GUARDARA Manager on the Development tab of the Settings page. 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.
Configuring the SDK
Issue the following command to configure the SDK.
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 an API Key. In case you do, you may want to provide it to the SDK. Having your API Key set up, you will be able to easily access it when using the API module of the SDK.
Using the SDK
Extension Development
GUARDARA allows users to develop extensions. GUARDARA operates with four extension types: Drivers, Monitors, Fields, and Transforms. The table below explains the purpose of each extension type.
| Extension Type | Description |
|---|---|
| Field | Fields are the basic building blocks of Message Templates, representing different fields within the modelled structured data. Fields generate test cases specific to the type of field they represent. |
| Transform | Transforms can be attached to a particular field or a group of fields. A Transform modifies the test case generated by the field it was attached to. An example of a transform could be Base64 encoding. |
| Driver | Drivers allow GUARDARA to communicate with the test targets in different ways. With custom drivers, it is possible to extend the capabilities of GUARDARA to deliver the test cases over different transport media. |
| Monitor | Monitors are extensions that allow GUARDARA to query the state of the test targets. |
Create 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 linked below and in the README.md file generated alongside the extension template files.
Package Extension
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>
Deploy Extension
There are two ways to deploy packaged extensions:
If you have set up API access during the SDK configuration and your API Key has the inventory:write or inventory:all scope assigned, 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 Inventory tab of the Settings page to upload your packaged extension.
Extension 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
It is highly recommended to test custom extensions thoroughly. Implement unit tests to ensure the code is working as expected.
A faulty extension will result in an error displayed run-time containing an error message along with the stack trace in the Activity Log section of the detailed test status page. Alternatively, errors can be viewed on the Engine’s information screen accessible from the Settings / Engines page by selecting the Engine and clicking the View Details button.
More Information
You can find additional information on implementing your extension in the README.md file generated by the SDK alongside the extension template files and in the remainder of the Developer's Guide. You can find even more information about implementing the different extensions within the generated source code.
Keep an eye out for the GUARDARA Community GitLab as we will be adding more and more examples. If you have a specific example in mind you would like to see, feel free to open a new issue for the project.