Overview

The purpose of this document is provide partners with an understanding of how to properly create Custom Attributes for the ThreatConnect Platform. These are primarily related to https://threatconnect-techpartners.atlassian.net/wiki/spaces/DP/pages/458975 integrations but may also be used with https://threatconnect-techpartners.atlassian.net/wiki/spaces/DP/pages/4522021 as well.

Define Custom Attributes Manually

The first step to defining custom attributes for an integration is to create them manually within the PartnerStage environment. Follow these steps:

1. From any screen, select the cogwheel menu at the top right and choose Org Config.

2. If you require any validation rules (a set of constraints on the input), you must define these first:

   1. The Attributes Type screen will be shown. Select the Attribute Validation Rules tab.

   2. Uncheck the box labeled Include System Rules and select the New button near the top left:
      
      

      Open

      

   3. The Create Attribute Validation Rule screen will be shown. Complete each field for your validation rule. It is recommended that only Regex or Date types be used here:

      Open

      

       

   4. Select Save to create each rule. Repeat this process as many times as necessary.

   5. Select the Attribute Types tab to return back to the original screen.

3. The Attribute Types screen will be shown. Uncheck the box labeled Include System Types and select the New button near the top left:

4. The Configure Attribute Type dialog will be shown. Complete each field that is required on the dialog using the help pop-ups as necessary. You must prefix your custom attributes with your company name such as “Farsight”. Validation rules should only be specified here if you’ve created them in the previous steps.

5. Select Save to create each new custom attribute type. Repeat this process for each custom attribute you require. These should remain present in your Organization configuration to be used as your model configurations (for future export, modifications, etc).

Test Custom Attribute Definitions

Once you have defined all of your custom attributes within your Organization, you must test them. Follow these steps to test each custom attribute type:

1. Navigate to an Indicator or Group type that matches what you specified for a given custom attribute type in the Mapping field. This Indicator or Group must exist within your Organization or a Source that you own (not the OSINT sources provided by default). If necessary, use the Create menu at the top of the system to create a new instance of this Indicator/Group within your Organization.

2. On the Indicator’s details page, scroll down to see the Attributes box on the left-hand side. Select the plus icon to add a new attribute.

3. The Edit Attribute screen will appear. Add your new custom attribute ensuring that you conform to any validation rules you specified. Select Save to add the attribute to the item.

    

4. Repeat this process for each of your custom attributes ensuring that they display properly and validate appropriately.

Export Custom Attributes

Once you’ve created your custom attributes and they have been validated completely using the steps above, you now need to export them so that they are available for other people to use. We will use a ThreatConnect Playbook to do this for simplicity. Follow these steps:

1. Download the attachment for this article that provides the Playbook from the listing above.

2. On the PartnerStage environment, select Playbooks from the menu at the top.

3. On the Playbooks screen, select New > Import Playbook:

    

4. On the Open dialog that appears, select the file you downloaded above (*.pbx file). The Playbook will be loaded into your environment and you will be shown the Designer screen.

5. On the Designer screen, toggle the Active switch at the top-right so that it shows the button to the right and has the info icon to the left:

    

6. Select the info icon and choose Execute Endpoint:

    

7. A new tab should open and you should be presented with a JSON document that contains all of your custom attributes. Output similar to the below should appear:
   
   

   { "types": [ { "allowMarkdown": false, "description": "Farsight DNSDB End Date", "errorMessage": "Invalid Date Format, Please Enter Farsight DNSDB End Date in YYYY-MM-DD format", "maxLength": 10, "name": "Farsight DNSDB End Date", "system": false, "version": 1, "indicators": [], "groups": [], "validationRule": { "name": "FarsightDateValidation", "type": "REGEX", "description": "Date should be in YYYY-MM-DD", "version": "1", "data": "^\\d{4}\\-(0[1-9]|1[012])\\-(0[1-9]|[12][0-9]|3[01])$" } }, { "allowMarkdown": false, "description": "Farsight DNSDB Start Date", "errorMessage": "Invalid Date Format, Please Enter Farsight DNSDB Start Date in YYYY-MM-DD format", "maxLength": 10, "name": "Farsight DNSDB Start Date", "system": false, "version": 1, "indicators": [], "groups": [], "validationRule": { "name": "FarsightDateValidation", "type": "REGEX", "description": "Date should be in YYYY-MM-DD", "version": "1", "data": "^\\d{4}\\-(0[1-9]|1[012])\\-(0[1-9]|[12][0-9]|3[01])$" } } ] }

    

8. Save this output as a JSON file.

9. Using a text editor, open the newly-saved JSON file and make the following modifications:

   1. For each item within the types list, add the appropriate values to the indicators and/or groups list for your attributes. These should be specified as the names that these items appear within the UI such as Address as an indicator type or Adversary as a group type. Specify each item within the list using double-quotes around the names and comma-separated to maintain proper JSON syntax. Here’s an example:

      "indicators": ["Host","Address"],

      NOTE: You must specify at least one value in the indicators or groups list. Leaving both blank is an invalid configuration.

10. Save all of your modifications and check the file for correct JSON syntax. Your file is now ready to be used for imports.

NOTE: Attributes are versioned and so please remember to increment the version when updating custom attributes through a JSON import. Otherwise, a previous version of the attribute might be used instead.

Test Import of Custom Attributes

Once you have successfully exported your attributes and made the appropriate updates to the file for your Indicator and Group assignments, follow these steps to import these attributes into your testing source:

1. From the system, select Posts from the top menu bar.

2. On the menu that appears on the left-hand side, select the item that is named “<Organization> Source”, such as “Farsight Source” for the “Farsight” Organization:

    

3. On the Source screen that appears, select the cogwheel at the top-left of the screen to configure the Source:

    

4. On the Source Config screen that appears, select the Upload button:
   
   

    

5. The Upload Attributes dialog will appear. Select the Select File option to select the JSON file you modified earlier for upload. The Upload Attributes screen will change to show the status of the file you’ve uploaded:
   
   

   NOTE: If you receive an error at this point, you may not have completed your file correctly. Specifically, if you receive the error “At least 1 entry must exist in either the indicators or groups array”, you must add the values to your JSON file as explained in the Export Custom Attributes section.

6. Select Save to commit your changes. Your new attributes should now be available for use in your testing Source.