Configuring and Writing Custom Plugins
Custom Plugins allow you to define customized API security tests by configuring how Traceable should mutate requests, validate, and report the identified vulnerabilities. You can write these plugins in YAML or Python according to your requirements.
This topic explains the different ways in which you can configure a custom plugin. It also explains how you can write a Custom YAML or Python Plugin along with the structure, required components, and detailed steps.
Ways to Configure a Custom Plugin
You can configure custom plugins in Traceable in either of the following ways:
Traceable platform (Recommended Method)
config.yamlfile
This section explains the steps to configure a custom plugin using the above options.
To create a custom plugin using the Traceable platform, navigate to Testing → Policies → Test Plugins and click Create in the page’s top right corner. Creating a custom plugin is a 3-step process:
Specify the custom plugin details and select the vulnerability type you want to detect using the plugin.
Specify the plugin definition according to your requirements.
Step 1 — General Details
This step requires you to specify the details for the plugin, along with the custom vulnerability you want Traceable to detect. The following is the list of fields you can configure:
Plugin name — The name of the custom plugin.
Description — Some basic information about the plugin, for example, the vulnerability it is detecting, and any references.
Attack Methodology — A description of the attack methodology that you are going to use in the plugin, for example, how it detects a vulnerability, tests the APIs.
Category — The category of the plugin:
Active — This category of plugins actively interacts with your application by making API calls to your application environment.
Passive — This category of plugins does not actively interact with your application and observe the calls made to your application environment.
(Optional) Safe for Production Environment — If disabled, Traceable does not use the custom plugin on your production environment, minimizing risks of impact on live data. If enabled, Traceable uses the custom plugin on your production environment.
(Optional) Tags — The metadata (key-value pairs) you want to apply to the plugin. For example, if the plugin detects vulnerabilities related to PCI DSS data, you can specify the key as Compliance with the value PCI DSS. To add multiple tags, click + Add Tag.
Vulnerability Type — Select or create the custom vulnerability you want Traceable to detect. Do either of the following:
Click the Select Vulnerability Types drop-down and select an existing vulnerability type. The drop-down lists the custom vulnerability types you may have created in the Vulnerability Types tab.
Click Create new, and in the pop-up window, specify the vulnerability type details according to your requirements. For more information, see Vulnerability Types.
Once you have selected a vulnerability type, click Next.
Step 2 — Plugin Definition
This step requires you to select the kind of custom plugin (Python or YAML) that you wish to create. After you have selected the plugin type, you can either upload the custom plugin code file or specify its code snippet. To upload the custom plugin file, click Import from file. For information on the attributes, functions, and operators you can use in a custom Python or YAML plugin, see Plugin Functions and Operators. For the steps to write a custom plugin, see Writing a Custom Plugin.
After you have specified the custom plugin code, Traceable also provides you with the option to test the plugin. To do so, you must complete the following configurations in the page’s right widget:
Endpoint selection — You can do the following to use an endpoint for testing:
Select an endpoint from the drop-down.
Click Advanced Search and select an API endpoint.
Specify the Endpoint URL.
Traceable populates the Request Headers and Request Body sections based on your selection. The selected endpoint acts as a reference. You can add Request Headers by clicking + Add Headers and Request Body according to your requirements. Traceable uses this request header and body for testing the plugin.
Runner selection — You can select a specific runner or allow Traceable to select one automatically. This runner is used for testing the plugin.
Run the scan — After you have completed the above step, click Run from the widget’s top right corner. Traceable displays the result below the Request Body section.
Once you have tested the plugin, click Submit. Traceable displays the plugin in the Test Plugins tab. You can also click the Ellipse () icon corresponding to a plugin to edit or delete it.
This method enables you to create custom Python plugins using the config.yaml file (plugins section) on your local machine. The following are configurations that you can use while creating the plugin:
Default Location — TRACEABLE_HOME
CLI — $HOME/.traceable
Docker — /app/userdata
config.yaml
$TRACEABLE_HOME
Contains the configuration for AST, such as pre-hooks, post-hooks, and custom plugin definitions.
custom
$TRACEABLE_HOME/plugins/custom
Contains the custom plugin implementations.
hooks
$TRACEABLE_HOME/hooks
Contains the pre- and post-hooks.
testsuite (per API)
$TRACEABLE_HOME/data/<scan_id>/*.json
Contains the JSON files that represent test suites. Each file is a suite of tests generated at the moment for a specific API.
Configuring custom plugins
The following section in the config.yaml file defines the custom plugins to load during the test runs:
In the above code snippet, the plugin name is sample_plugin, which should match the name of the plugin defined in the custom Python plugin code placed in the $TRACEABLE_HOME/plugins/custom directory. For information on the attributes, functions, and operators you can use in a custom Python plugin, see Plugin Functions and Operators. For the steps to write a custom plugin, see Writing a Custom Plugin.
Traceable also provides AI plugins that you can use to detect AI-related issues. In these AI plugins, you can update the prompt key in the config.yaml file using the following code:
Writing a Custom Plugin
You can write Custom Plugins in either YAML or Python, based on your comfort level and use-case complexity. While YAML-based plugins provide a clean and direct declarative approach, the Python-based plugins provide full programmatic control and flexibility over the plugin definition.
In either approach, writing a custom plugin is a multi-step process. The following sections highlight the plugin's scenario and provide its summary.
Scenario: Mass Assignment Vulnerability Detection during User Registration
The below plugin simulates a Mass Assignment attack where it tests whether an attacker can exploit request payloads to gain unauthorized access (admin access) during user registration.
This scenario mirrors a common API security weakness where an unfiltered client-side input leads to unauthorized privilege, and is highlighted in the OWASP API Top 10 under API6:2023 - Unrestricted Access to Sensitive Business Flows.
Following is a summary of the steps in the plugin:
Create a Baseline to verify whether the registration endpoint in your application returns the expected output without any modifications.
Mutate (Modify) the request by adding parameters like
admin=trueand modifying fields likeusernameandemail. This simulates the attempt of an attacker who might suspect that your application code does not validate the user-specified fields against the API schema.Assert (Validate) the response to check whether the added and modified fields are accepted by the application code and if the registration succeeds unexpectedly.
Send a follow-up request to the endpoint to confirm whether the newly registered user received admin privileges. This final step confirms the presence of the mass assignment vulnerability.
The following tabs highlight the above steps in detail, along with the custom plugin code. Click the tabs according to your requirements and complete the steps to write your custom YAML or Python plugin.
Step 1 — Define the Vulnerability Type and Attributes
Before you create a baseline test, you must define the test name and other attributes as mentioned below.
Step 2 — Adding Baseline Tests
As mentioned above, start by creating a baseline test. This helps you understand the endpoint’s expected behavior before creating the main attack.
Step 3 — Chaining a new test for the attack
Once you have created the above baseline tests, you can now mutate the request and try to trigger a vulnerability. In the below code, tests are chained because they are supposed to be executed only when the above baseline test (Step 2) returns NOT_OK as the result.
Step 4 — Add Mutations to modify the parameters
Now that you have specified the test details, you can specify the mutations and the parameter details to test for the mass assignment vulnerability.
Step 5 — Add Assertions to detect unexpected behavior
Based on the mutated parameters, you can specify the assertions to validate the API response towards the mutated data.
Step 6 — Add another chain for further Admin validation
As part of this step, you add another chain to follow up the above test. Here, Traceable verifies if the admin privileges were actually granted to the mutated user.
Step 7 — Add Mutations to modify parameters for admin validation
Add the mutations as part of the validation test. This test changes the request path and method to check the availability of the admin field for the mutated user above.
Step 7 — Add Assertions to confirm exploitation
This assertion validates whether the vulnerability is successfully exploited using the above attacks.
Combined Custom YAML Plugin
Following is the custom YAML plugin code that combines all the above steps:
Step 1 — Import the Required Modules and Set Up Logging
As part of writing a Custom Python Plugin, you must import its core modules. These modules enable you to create test logic, modify the requests or responses, validate them, define dependency chains, etc.
Step 2 — Define the Plugin Class and Metadata
Define the plugin identity and behavior using the mandatory and optional fields. Some of these fields are used to specify the vulnerability information on the Traceable platform.
Step 3 — Initialize the Plugin
Define the init method to ensure that the plugin has access to scanning APIs and the related metadata.
Step 4 — Set up the Run Method
Define the main execution point of the plugin. The logic below ensures that the plugin runs only once per API per scan. Additionally, on each execution, the plugin populates the logger message, which helps during any debugging.
Step 5 — Create the Baseline Test
Once you have defined the metadata and other methods, start by creating a baseline test. This test helps you understand the endpoint’s expected behavior before creating the main attack. The observed behavior is compared against that observed in the main test.
Add baseline assertions for validation of the following:
The ideal response code (
${original.http.response.code}) should match the mutated response code (${mutated.http.response.code})The request URL should be the user registration endpoint
Step 6 — Create the Main Attack
Once you have created the above baseline tests, you can now create the main attack that mutates the request and tries to trigger a vulnerability. In this step, tests are chained because they are supposed to be executed only when the above baseline test (Step 5) returns NOT_OK as the result.
Add request mutations. These mutations perform the following:
Sets the Admin parameter (
${mutated.http.request.body.admin}) to True.Modifies the user email (
${mutated.http.request.body.*email}) to a dummy one.Modifies the username (
${mutated.http.request.body.*username}) to a dummy one.
Add request assertions for validation of the following:
The response body (
mutated.http.response.body.status) contains success as the status.The mutated response code (
${mutated.http.response.code}) is the same as the original one (${original.http.response.code}).
As mentioned above, chain this main attack to the above baseline test.
Step 7 — Add a Validation Test to Confirm Exploitation
As part of this step, you add another chain to follow up the above test. Here, Traceable verifies if the admin privileges were actually granted to the mutated user. Here, tests are chained because they are supposed to be executed only when the above baseline test (Step 5) returns NOT_OK as the result.
Add request mutations. These mutations perform the following:
Modifies the request path (
mutated.http.request.path) to retrieve user details.Modifies the request method (
mutated.http.request.method) toGET.
Add request assertions for validation of the following:
The mutated response code (
${mutated.http.response.code}) is the same as the original one (${original.http.response.code}).The response body (
${mutated.http.response.body}) contains theadminfield astruefor the dummy user.
As mentioned above, chain the baseline test with the main attack, and the main attack with the validation test.
Step 8 — Run the Tests and Upload Results
Execute the test and upload the results to the Traceable platform.
Combined Custom Python Plugin
Following is the Custom Python Plugin code that combines all the above steps:
Last updated
Was this helpful?