# Custom Fields & Forms

{% embed url="<https://www.youtube.com/watch?v=vPZU3LxqvUE>" %}

## Overview

AttackForge supports ability to create custom fields & forms. This can help to capture information which is relevant to your organization and customers.

Custom fields can be accessed in the application, in reports and also via the Self-Service APIs.

You can create custom fields & forms for the following:

* Project Request
* Project
* Writeups
* Vulnerabilities
* Assets
* Portfolios
* Test Cases
* Project Test Cases
* Reporting
* Project Pages
* Groups

To set custom fields, you must be an Administrator. Start by clicking on `Administration` module, then click on any of the following sections:

* Portfolios
* Projects
* Project Requests
* Vulnerabilities
* Test Cases
* Reporting
* Pages
* Assets
* Writeups
* Test Suites
* Groups

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2F9OxrO7pKrgCUjZ5dw4Bi%2FScreenshot%202024-07-06%20at%203.44.01%E2%80%AFPM.png?alt=media&#x26;token=50db99b1-ed33-4879-b89f-dd5cb827c30f" alt=""><figcaption></figcaption></figure>

AttackForge supports custom `Sections` which can be used to group custom fields together in the form.

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FWL0pGRswywZKoTdInc4k%2FScreenshot%202024-07-06%20at%203.46.33%E2%80%AFPM.png?alt=media&#x26;token=412a6115-cbfb-4cab-b550-c50cacc80fe0" alt=""><figcaption></figcaption></figure>

AttackForge supports the following custom field types:

* Input field
* Text Area
* Select
* Multi-Select
* List
* Datepicker
* Datetimepicker
* Table
* Rich-Text
* User Select
* User Multi-Select
* Group Select
* Group Multi-Select

## **Input Fields**

Input fields display a single-line input box within the relevant forms.

When creating an input field, the following options are available:

* **Key** - This the name of the field (e.g. database field name). This is the reference you will use when referring to this field in the JSON export, ReportGen or via the Self-Service API. The key must be unique, and is limited to alpha-numeric and underscores only.
* **Placeholder Value** - This is the default value that will be displayed in the forms.
* **Label** - This is the label that will be displayed in the form for this field, as well as in the data tables.
* **Info** - This is a custom information message that will display to the user when they have selected the field or are entering information into the field.
* **Required** - This is used to determine whether the field is mandatory or optional in the forms.
* **Display in Tables** - This is used to determine whether the field will be displayed as a new column in the relevant tables within the application.
* **Hide Condition** - This is used to create a condition to hide the field, until such condition is met. See [Hide Conditions](#hide-conditions) for more details.
* **Access Controls** - This is used to configure which Roles, Groups or Users will have access to see or modify this field and its data.

## **Text Area Fields**

Text area fields display multi-line input box within the relevant forms. Text area can be resized by the user within the form if additional space is needed. This option is useful if user is required to enter paragraphs of text.

When creating a text area field, the following options are available:

* **Key** - This the name of the field (e.g. database field name). This is the reference you will use when referring to this field in the JSON export, ReportGen or via the Self-Service API. The key must be unique, and is limited to alpha-numeric and underscores only.
* **Placeholder Value** - This is the default value that will be displayed in the forms.
* **Label** - This is the label that will be displayed in the form for this field, as well as in the data tables.
* **Info** - This is a custom information message that will display to the user when they have selected the field or are entering information into the field.
* **Required** - This is used to determine whether the field is mandatory or optional in the forms.
* **Display in Tables** - This is used to determine whether the field will be displayed as a new column in the relevant tables within the application.
* **Hide Condition** - This is used to create a condition to hide the field, until such condition is met. See [Hide Conditions](#hide-conditions) for more details.
* **Access Controls** - This is used to configure which Roles, Groups or Users will have access to see or modify this field and its data.

## **Select Fields**

Select fields display a drop-down menu with a single item select within the relevant forms. User can only select one option.

When creating a select field, the following options are available:

* **Key** - This the name of the field (e.g. database field name). This is the reference you will use when referring to this field in the JSON export, ReportGen or via the Self-Service API. The key must be unique, and is limited to alpha-numeric and underscores only.
* **Default Select Option** - This is the default option that will be selected on the forms.
* **Label** - This is the label that will be displayed in the form for this field, as well as in the data tables.
* **Info** - This is a custom information message that will display to the user when they have selected the field or are entering information into the field.
* **Required** - This is used to determine whether the field is mandatory or optional in the forms.
* **Display in Tables** - This is used to determine whether the field will be displayed as a new column in the relevant tables within the application.
* **Hide Condition** - This is used to create a condition to hide the field, until such condition is met. See [Hide Conditions](#hide-conditions) for more details.
* **Access Controls** - This is used to configure which Roles, Groups or Users will have access to see or modify this field and its data.
* **Add Select Option** - this button will create a new option for the menu. The menu must have at least one option.&#x20;
  * **Option** - The option is the text that will be displayed in the drop-down menu within the form.
  * **Value** - The value is the data that will represent this option when it is selected by a user.

## **Multi-Select Fields**

Multi-select fields displays a drop-down menu with a multi-item select within the relevant forms. User can select one or more options.

When creating a multi-select field, the following options are available:

* **Key** - This the name of the field (e.g. database field name). This is the reference you will use when referring to this field in the JSON export, ReportGen or via the Self-Service API. The key must be unique, and is limited to alpha-numeric and underscores only.
* **Default Select Options** - This is the default options that will be selected on the forms. You can specify multiple options by separating each option with a comma e.g. *pcidss,hipaa*
* **Label** - This is the label that will be displayed in the form for this field, as well as in the data tables.
* **Info** - This is a custom information message that will display to the user when they have selected the field or are entering information into the field.
* **Required** - This is used to determine whether the field is mandatory or optional in the forms.
* **Display in Tables** - This is used to determine whether the field will be displayed as a new column in the relevant tables within the application.
* **Hide Condition** - This is used to create a condition to hide the field, until such condition is met. See [Hide Conditions](#hide-conditions) for more details.
* **Access Controls** - This is used to configure which Roles, Groups or Users will have access to see or modify this field and its data.
* **Add Select Option** - this button will create a new option for the menu. The menu must have at least one option.&#x20;
  * **Option** - The option is the text that will be displayed in the drop-down menu within the form.
  * **Value** - The value is the data that will represent this option when it is selected by a user.

## **List Fields**

List fields display an input field with an option to add additional rows of input fields, similar to when typically adding tags.

When creating a list field, the following options are available:

* **Key** - This the name of the field (e.g. database field name). This is the reference you will use when referring to this field in the JSON export, ReportGen or via the Self-Service API. The key must be unique, and is limited to alpha-numeric and underscores only.
* **Label** - This is the label that will be displayed in the form for this field, as well as in the data tables.
* **Info** - This is a custom information message that will display to the user when they have selected the field or are entering information into the field.
* **Required** - This is used to determine whether the field is mandatory or optional in the forms.
* **Display in Tables** - This is used to determine whether the field will be displayed as a new column in the relevant tables within the application.
* **Hide Condition** - This is used to create a condition to hide the field, until such condition is met. See [Hide Conditions](#hide-conditions) for more details.
* **Access Controls** - This is used to configure which Roles, Groups or Users will have access to see or modify this field and its data.

## Datepicker Field

The datepicker fields display a calendar where the user can select a single date.

When creating a datepicker field, the following options are available:

* **Key** - This the name of the field (e.g. database field name). This is the reference you will use when referring to this field in the JSON export, ReportGen or via the Self-Service API. The key must be unique, and is limited to alpha-numeric and underscores only.
* **Placeholder Date** - This is the default date that will be displayed in the forms.
* **Label** - This is the label that will be displayed in the form for this field, as well as in the data tables.
* **Info** - This is a custom information message that will display to the user when they have selected the field or are entering information into the field.
* **Required** - This is used to determine whether the field is mandatory or optional in the forms.
* **Display in Tables** - This is used to determine whether the field will be displayed as a new column in the relevant tables within the application.
* **Access Controls** - This is used to configure which Roles, Groups or Users will have access to see or modify this field and its data.
* **Hide Condition** - This is used to create a condition to hide the field, until such condition is met. See [Hide Conditions](#hide-conditions) for more details.

## Datetimepicker Field

The datetimepicker fields display a calendar where the user can select a single date and enter in a time.

When creating a datetimepicker field, the following options are available:

* **Key** - This the name of the field (e.g. database field name). This is the reference you will use when referring to this field in the JSON export, ReportGen or via the Self-Service API. The key must be unique, and is limited to alpha-numeric and underscores only.
* **Placeholder Date** - This is the default date that will be displayed in the forms.
* **Label** - This is the label that will be displayed in the form for this field, as well as in the data tables.
* **Info** - This is a custom information message that will display to the user when they have selected the field or are entering information into the field.
* **Required** - This is used to determine whether the field is mandatory or optional in the forms.
* **Display in Tables** - This is used to determine whether the field will be displayed as a new column in the relevant tables within the application.
* **Access Controls** - This is used to configure which Roles, Groups or Users will have access to see or modify this field and its data.
* **Hide Condition** - This is used to create a condition to hide the field, until such condition is met. See [Hide Conditions](#hide-conditions) for more details.

## Table Field

The table field displays ability to define columns, where the user can then create rows of data against these columns.

When creating a table field, the following options are available:

* **Key** - This the name of the field (e.g. database field name). This is the reference you will use when referring to this field in the JSON export, ReportGen or via the Self-Service API. The key must be unique, and is limited to alpha-numeric and underscores only.
* **Label** - This is the label that will be displayed in the form for this table.
* **Info** - This is a custom information message that will display to the user when they have selected the field or are entering information into the field.
* **Required** - This is used to determine whether the table is mandatory or optional in the forms.
* **Hide Condition** - This is used to create a condition to hide the field, until such condition is met. See [Hide Conditions](#hide-conditions) for more details.
* **Access Controls** - This is used to configure which Roles, Groups or Users will have access to see or modify this field and its data.

You can then add columns by clicking Add Column. Each column has the following options:

* **Type** - Input field, Text Area, Select, Multi-Select or Datepicker
* **Key** - This the name of the field (e.g. database field name). This is the reference you will use when referring to this field in the JSON export, ReportGen or via the Self-Service API. The key must be unique, and is limited to alpha-numeric and underscores only.
* **Info** - This is a custom information message that will display to the user when they have selected the field or are entering information into the field.
* **Default Value / Selected Options** - depending on the Type, this will allow you to specify default selected options/value for this field.
* **Label** - This is the label that will be displayed in the form for this table.
* **Required** - This is used to determine whether the table is mandatory or optional in the forms.

The form will present all of the columns (fields) for the user to enter, and ability to add rows.

## **Rich-Text Fields**

Rich-Text fields display a multi-line WYSIWYG input box within the relevant forms.

When creating an rich-text field, the following options are available:

* **Key** - This the name of the field (e.g. database field name). This is the reference you will use when referring to this field in the JSON export, ReportGen or via the Self-Service API. The key must be unique, and is limited to alpha-numeric and underscores only.
* **Placeholder Value** - This is the default value that will be displayed in the forms.
* **Label** - This is the label that will be displayed in the form for this field, as well as in the data tables.
* **Info** - This is a custom information message that will display to the user when they have selected the field or are entering information into the field.
* **Required** - This is used to determine whether the field is mandatory or optional in the forms.
* **Hide Condition** - This is used to create a condition to hide the field, until such condition is met. See [Hide Conditions](#hide-conditions) for more details.
* **Access Controls** - This is used to configure which Roles, Groups or Users will have access to see or modify this field and its data.

## **User Select Fields**

User Select fields display a drop-down menu with a single item select within the relevant forms.&#x20;

The user will be able to select a single user in the application from the drop-down list.

> **!IMPORTANT:** This field type is restricted to access controls. An access control must be applied in order for this field type to be set. Any user with View privileges to this field will be able to view the input user and their profile. Any user with Edit privileges will be able to see all users in the system, including their first name, last name and email address. This is required in order to be able to select a user from the system.

When creating a user select field, the following options are available:

* **Key** - This the name of the field (e.g. database field name). This is the reference you will use when referring to this field in the JSON export, ReportGen or via the Self-Service API. The key must be unique, and is limited to alpha-numeric and underscores only.
* **Default Select Option** - This is the default option that will be selected on the forms.
* **Label** - This is the label that will be displayed in the form for this field, as well as in the data tables.
* **Info** - This is a custom information message that will display to the user when they have selected the field or are entering information into the field.
* **Required** - This is used to determine whether the field is mandatory or optional in the forms.
* **Display in Tables** - This is used to determine whether the field will be displayed as a new column in the relevant tables within the application.
* **Hide Condition** - This is used to create a condition to hide the field, until such condition is met. See [Hide Conditions](#hide-conditions) for more details.
* **Access Controls** - This is used to configure which Roles, Groups or Users will have access to see or modify this field and its data.

## **User Multi-Select Fields**

User Multi-Select fields display a drop-down menu with a multi item select within the relevant forms.&#x20;

The user will be able to select multiple users in the application from the drop-down list.

> **!IMPORTANT:** This field type is restricted to access controls. An access control must be applied in order for this field type to be set. Any user with View privileges to this field will be able to view the input user and their profile. Any user with Edit privileges will be able to see all users in the system, including their first name, last name and email address. This is required in order to be able to select a user from the system.

When creating a user multi-select field, the following options are available:

* **Key** - This the name of the field (e.g. database field name). This is the reference you will use when referring to this field in the JSON export, ReportGen or via the Self-Service API. The key must be unique, and is limited to alpha-numeric and underscores only.
* **Default Select Option** - This is the default option that will be selected on the forms.
* **Label** - This is the label that will be displayed in the form for this field, as well as in the data tables.
* **Info** - This is a custom information message that will display to the user when they have selected the field or are entering information into the field.
* **Required** - This is used to determine whether the field is mandatory or optional in the forms.
* **Display in Tables** - This is used to determine whether the field will be displayed as a new column in the relevant tables within the application.
* **Hide Condition** - This is used to create a condition to hide the field, until such condition is met. See [Hide Conditions](#hide-conditions) for more details.
* **Access Controls** - This is used to configure which Roles, Groups or Users will have access to see or modify this field and its data.

## **Group Select Fields**

Group Select fields display a drop-down menu with a single item select within the relevant forms.&#x20;

The user will be able to select a single group in the application from the drop-down list.

> **!IMPORTANT:** This field type is restricted to access controls. An access control must be applied in order for this field type to be set. Any user with View privileges to this field will be able to view the input group name. Any user with Edit privileges will be able to see all groups in the system. This is required in order to be able to select a group from the system.

When creating a group select field, the following options are available:

* **Key** - This the name of the field (e.g. database field name). This is the reference you will use when referring to this field in the JSON export, ReportGen or via the Self-Service API. The key must be unique, and is limited to alpha-numeric and underscores only.
* **Default Select Option** - This is the default option that will be selected on the forms.
* **Label** - This is the label that will be displayed in the form for this field, as well as in the data tables.
* **Info** - This is a custom information message that will display to the user when they have selected the field or are entering information into the field.
* **Required** - This is used to determine whether the field is mandatory or optional in the forms.
* **Display in Tables** - This is used to determine whether the field will be displayed as a new column in the relevant tables within the application.
* **Hide Condition** - This is used to create a condition to hide the field, until such condition is met. See [Hide Conditions](#hide-conditions) for more details.
* **Access Controls** - This is used to configure which Roles, Groups or Users will have access to see or modify this field and its data.

## **Group Multi-Select Fields**

Group Select fields display a drop-down menu with a multi item select within the relevant forms.&#x20;

The user will be able to select multiple groups in the application from the drop-down list.

> **!IMPORTANT:** This field type is restricted to access controls. An access control must be applied in order for this field type to be set. Any user with View privileges to this field will be able to view the input group name. Any user with Edit privileges will be able to see all groups in the system. This is required in order to be able to select a group from the system.

When creating a group select field, the following options are available:

* **Key** - This the name of the field (e.g. database field name). This is the reference you will use when referring to this field in the JSON export, ReportGen or via the Self-Service API. The key must be unique, and is limited to alpha-numeric and underscores only.
* **Default Select Option** - This is the default option that will be selected on the forms.
* **Label** - This is the label that will be displayed in the form for this field, as well as in the data tables.
* **Info** - This is a custom information message that will display to the user when they have selected the field or are entering information into the field.
* **Required** - This is used to determine whether the field is mandatory or optional in the forms.
* **Display in Tables** - This is used to determine whether the field will be displayed as a new column in the relevant tables within the application.
* **Hide Condition** - This is used to create a condition to hide the field, until such condition is met. See [Hide Conditions](#hide-conditions) for more details.
* **Access Controls** - This is used to configure which Roles, Groups or Users will have access to see or modify this field and its data.

## Hide Expressions/Conditions

Hide expressions or conditions are used to hide a custom field or custom section until some condition is met.

Using the example below, let's say we have two (2) custom fields for a project request:

* **project\_type** - this field allows the person requesting the project to pick what type of project they are requesting, for example a web app pentest, vulnerability scan, code review, etc.
* **application\_url** - this field is used to capture the URL for the application IF the person is requesting a web app pentest.

Let's say we want to hide the **application\_url** field until the user has selected 'Web App Pentest' from the **project\_type** select menu.

We would enter the following hide condition into the **application\_url** field:

```
custom.project_type !== "web_app_pentest"
```

This hide condition states: *Hide this field WHILE project\_type is NOT EQUAL to web\_app\_pentest*

As a result, the project request form will not show this field until the user has selected 'Web App Pentest' as the type of assessment they are requesting.

Hide conditions support additional logical expressions, such as:

{% code overflow="wrap" %}

```
custom.project_type !== "web_app_pentest" AND custom.project_type !== "vuln_scan"
```

{% endcode %}

This hide condition states: *Hide this field WHILE project\_type is NOT EQUAL to web\_app\_pentest AND project\_type is NOT EQUAL to vuln\_scan*

This is useful if we want this field to display on either a Web App Pentest or Vulnerability Scan.

```
custom.project_type == "web_app_pentest
```

This hide condition states: *Hide this field WHILE project*\_*type is EQUAL to web\_app\_pentest*

{% code overflow="wrap" %}

```
custom.project_type !== "web_app_pentest" AND custom.company_name !== undefined
```

{% endcode %}

This hide condition states: *Hide this field WHILE project\_type is NOT EQUAL to web\_app\_pentest AND company\_name is not empty i.e. user has entered a value for company name field*

Another example is showing a field "WEB APP Q1" only when a user selects "Web App" from another field. This example works for both Select & Multi-Select.

{% code overflow="wrap" %}

```
custom.test_type == undefined OR custom.test_type.length < 1 OR custom.test_type.length > 0 AND custom.test_type.indexOf("web_app") < 0
```

{% endcode %}

### Referring to Fields

You can refer to fields using the following syntax:

* **core.\<key>** - refers to a system field with a well-known key (see sections below)
* **custom.\<key>** - refers to a custom field with a user-defined key

> **!IMPORTANT:** For Vulnerability Custom Fields - you can also refer to project custom fields. The syntax works as follows:

* **project.core.\<key>** - refers to a project system field from a vulnerability custom field hide expression.
* **project.custom.\<key>** - refers to a project custom field with a user-defined key from a vulnerability custom field hide expression.

> **IMPORTANT:** For Project Test Case Custom Fields - you can also refer to project and test case (from test suite) custom fields. The syntax works as follows:

* **project.core.\<key>** - refers to a project system field from a vulnerability custom field hide expression.
* **project.custom.\<key>** - refers to a project custom field with a user-defined key from a vulnerability custom field hide expression.
* **test\_case.core.\<key>** - refers to a test case system field from a project test case custom field hide expression.
* **test\_case.custom.\<key>** - refers to a test case custom field with a user-defined key from a project test case custom field hide expression.

> **IMPORTANT**: When Approving a Project Request, you can refer to both Project Request and Project fields as follows:

* **project\_request.core.\<key>** - refers to a project request system field from a project custom field hide expression.
* **project\_request.custom.\<key>** - refers to a project request custom field with a user-defined key from a project custom field hide expression.
* **project.core.\<key>** - refers to a project system field from a project custom field hide expression.
* **project.custom.\<key>** - refers to a project custom field with a user-defined key from a project custom field hide expression.

### Operators

* **NOT** or **!** - used to negate an expression. For example *!(core.\<key> === "...")*
* **AND** or **&&** - used to *and* multiple expressions. For example *core.\<key> === "..." AND core.\<key> === "..."*
* **OR** or **||** - used to *or* multiple expressions. For example *core.\<key> === "..." OR core.\<key> === "..."*
* **==** - used to check for equivalency. For example *core.\<key> == "..."*
* **===** - used to check for equality. For example *core.\<key> === "..."*
* **!==** - used to check for not equivalency. For example *core.\<key> !== "..."*
* **>** - used to check for greater-than comparison. For example *core.\<key> > 10*
* **<** - used to check for less-than comparison. For example *core.\<key> < 10*
* **>**= - used to check for greater-than-or-equals comparison. For example *core.\<key> >= 10*
* **<=** - used to check for less-than-or-equals comparison. For example *core.\<key> <= 10*
* **( )** - used to group statements together. For example ((*core.\<key>* === "...") AND (*core.\<key> === "..."*)) OR ((*core.\<key>* === "...") AND (*core.\<key> == "..."*))

### Field types

#### **string**

Refers to a string value.&#x20;

Example: *Project Request "name" System Field*

This rule will hide the field until the project name on the project request has at least 1 character filled in.

```
core.name.length < 1
```

This rule will show the field until the project name on the project request has at least 1 character filled in.

```
core.name.length > 0
```

This rule will hide the field until the project name on the project request is exactly "Project Name".

```
core.name !== "Project Name"
```

This rule will show the field until the project name on the project request is exactly "Project Name".

```
core.name == "Project Name"
```

#### **string\[]**

Refers to a string array / array of strings.

Example: *Project Request "testing\_to\_be\_performed" System Field*

This rule will hide the field until the user has selected a particular service / test type.

```
core.testing_to_be_performed == undefined OR core.testing_to_be_performed.length < 1 OR core.testing_to_be_performed.length > 0 AND core.testing_to_be_performed.indexOf("62e0d2b6e326df35c2a4bdf4") < 0
```

It works as follows:

* **core.testing\_to\_be\_performed == undefined OR core.testing\_to\_be\_performed.length < 1**
  * Hide the field if user has not selected any test types
* **|| core.testing\_to\_be\_performed.length > 0 AND core.testing\_to\_be\_performed.indexOf("62e0d2b6e326df35c2a4bdf4") < 0**
  * Hide the field if user has selected a test type(s), but the test type(s) does not contain the ID of a particular test suite e.g. 62e0d2b6e326df35c2a4bdf4. Note you can get the ID of a test suite by checking the URL when visiting the test suite in the Test Suites module.

**ISO date time**

Refers to a datetime in ISO format e.g. YYYY-MM-DD-Thh:mm:ss.mmmZ

Example: *Project "start\_date" System Field*

This rule will hide the field until the user has selected a date greater than 1st of January 2023.

```
core.start_date == undefined OR core.start_date < "2023-01-01T00:00:00.000Z"
```

#### Number

Refers to an integer i.e. 1, 2 or 10

Example: *Vulnerability "exploitability" System Field*

This rule will hide the field until the user has selected a Likelihood of Exploitation greater than or equal to 5.

```
core.exploitability == undefined OR core.exploitability < 5
```

#### Boolean

Refers to a boolean i.e. true or false

Example: *Vulnerability "zero\_day" System Field*

This rule will hide the field until the user has selected Yes for Is Zero Day? field.

```
core.zero_day == undefined OR core.zero_day == false
```

### Project System Fields

* **name** (string | undefined)
* **code** (string | undefined)
* **org\_code** (string | undefined)
* **start\_date** (ISO date time | undefined)
* **end\_date** (ISO date time | undefined)
* **timeframe** (ISO date time | undefined, ISO date time | undefined)
* **linked\_groups** (string\[] | undefined)
* **group\_ids** (string\[] | undefined)
* **group\_names** (string\[] | undefined)
* **portfolio\_ids** (string\[] | undefined)
* **portfolio\_names** (string\[] | undefined)
* **portfolio\_stream\_ids** (string\[] | undefined)
* **portfolio\_stream\_names** (string\[] | undefined)
* **test\_suite\_ids** (string\[] | undefined)
* **test\_suite\_names** (string\[] | undefined)
* **vuln\_scoring\_system** ('CVSS v3.1 Baseline' | 'CVSS v3.1 Baseline + Temporal' | 'CVSS v3.1 Baseline + Temporal + Environmental' | undefined)
* **vuln\_code** (string | undefined)
* **sla\_apply\_method** ('Automatic' | 'Manual' | undefined)

### Project Request System Fields

* **name** (string | undefined)
* **code** (string | undefined)
* **linked\_groups** (string\[] | undefined)
* **onsite\_testing\_required** ('Yes' | 'No' | undefined)
* **reason\_testing\_is\_required** (string | undefined)
* **desired\_test\_window** ('Mon-Fri (Business Hours)' | 'Mon-Fri (Non-Business Hours)' | 'Weekends (Sat/Sun)' | undefined)
* **testing\_to\_be\_performed** (string\[] | string | undefined)
* **scope** (string\[] | undefined)
* **desired\_start\_date** (string | undefined)
* **desired\_end\_date** (string | undefined)
* **org\_code** (string | undefined)

### Vulnerability System Fields

* **writeup\_library** (object | undefined)
  * **name** (string)
  * **key** (string)
  * **type** ('system' | 'custom')
* **writeup** (object | undefined)
  * **id** (string)
  * **name** (string)
* **asset\_names** (string\[])
* **zero\_day** (true | false | undefined)
* **visibility\_to\_project\_team** (true | false | undefined)
* **priority** ('Critical' | 'High' | 'Medium' | 'Low' | 'Info' | undefined)
* **exploitability** (number | undefined)
* **steps\_to\_reproduce** (string | undefined)
* **notes** (string\[] | undefined)
* **tags** (string\[] | undefined)
* **associated\_test\_cases** (string\[] | undefined)
* **project.core.\<key> -** refer to a project system field
* **project.custom.\<key>** - refer to a project custom field

### Writeup System Fields

* **library** (object | undefined)
  * **type** ('system' | 'custom')
  * **key** (string)
* **import\_source** (string | undefined)
* **import\_source\_id** (string | undefined)
* **template** (string | undefined)
* **title** (string | undefined)
* **description** (string | undefined)
* **attack\_scenario** (string | undefined)
* **remediation\_recommendation** (string | undefined)
* **severity** (number | undefined)
* **exploitability** (number | undefined)
* **impact\_on\_confidentiality** ('High' | 'Medium' | 'Low' | 'None' | undefined)
* **impact\_on\_integrity** ('High' | 'Medium' | 'Low' | 'None' | undefined)
* **impact\_on\_availability** ('High' | 'Medium' | 'Low' | 'None' | undefined)
* **tags** (string\[] | undefined)

### Asset System Fields

* **name** (string | undefined)
* **type** (string | undefined)
* **id** (string | undefined)
* **details** (string | undefined)
* **linked\_groups** (string\[] | undefined)

### Portfolio System Fields

* **name** (string | undefined)
* **code** (string | undefined)
* **description** (string | undefined)
* **level1\_owner** (string | undefined)
* **level2\_owner** (string | undefined)
* **level3\_owner** (string | undefined)
* **tags** (string\[] | undefined)

### Test Case System Fields

* **test\_case** (string | undefined)
* **details** (string | undefined)
* **code** (string | undefined)
* **execution\_flow** ({ title: string, details: string }\[] | \[])
* **tags** (string\[] | \[])

### Project Test Case System Fields

* **status** ('Tested', 'Not Tested', 'Testing In Progress', 'Not Applicable' | undefined)
* **assigned\_to** (string | undefined)
* **project.core.\<key> -** refer to a project system field
* **project.custom.\<key>** - refer to a project custom field
* **test\_case.core.\<key>** - refer to a test case system field
* **test\_case.custom.\<key> -** refer to a test case custom field

### Group System Fields

* **name** (string | undefined)
* **owner** (string | undefined)
* **primary\_contact** (object | undefined)
  * **name** (string | undefined)
  * **number** (string | undefined)
  * **email** (string | undefined)

## Project Request Custom Fields

From the `Administration` module, click on `Projects -> Project Requests` then click on Add Custom Field in Project Requests section.

Add the custom fields you would like displayed in the forms and tables. Set the options as required for each field, then click Update.

You can view the custom fields in the following forms, pages and tables:

* Request a New Project / Edit Project Request forms
* Viewing a Project Request page
* Approve Project Request with Updates form
* Pending Requests table in Projects Module
* Actioned Requests table in Projects Module

## Project Custom Fields

From the `Administration` module, click on `Projects` then click on Add Custom Field in Projects section.

Add the custom fields you would like displayed in the forms and tables. Set the options as required for each field, then click Update.

You can view the custom fields in the following forms, pages and tables:

* Create New Project / Edit Project forms
* Approve Project Request form
* Project Dashboard
* Projects and Archived Projects tables in Projects Module
* Viewing projects in reports

## Writeups Custom Fields

From the `Administration` module, click on `Writeups` then click on Add Custom Field.

Add the custom fields you would like displayed in the forms and tables. Set the options as required for each field, then click Update.

You can view the custom fields in the following forms, pages and tables:

* Create a New Writeup / Edit Writeup forms
* Viewing a writeup in the library
* Viewing a vulnerability on a project
* Writeups tables in Writeups Module
* Viewing writeups in reports

## Vulnerability Custom Fields

From the `Administration` module, click on `Projects -> Vulnerabilities` then click on Add Custom Field.

Add the custom fields you would like displayed in the forms and tables. Set the options as required for each field, then click Update.

You can view the custom fields in the following forms, pages and tables:

* Create a New Vulnerability / Edit Vulnerability forms
* Viewing a vulnerability on a project
* Vulnerabilities tables
* Viewing vulnerabilities in reports

## Asset Custom Fields

From the `Administration` module, click on `Assets` then click on Add Custom Field.

Add the custom fields you would like displayed in the forms and tables. Set the options as required for each field, then click Update.

You can view the custom fields in the following forms, pages and tables:

* Create or Update an Asset within Asset Module
* Viewing an Asset within Assets module
* Assets table
* Viewing assets in reports

## Portfolio Custom Fields

From the `Administration` module, click on `Portfolios` then click on Add Custom Field.

Add the custom fields you would like displayed in the forms and tables. Set the options as required for each field, then click Update.

You can view the custom fields in the following forms, pages and tables:

* Create or Update a Portfolio within Portfolios Module
* Viewing a portfolio
* Portfolios table

## Test Case Custom Fields

From the `Administration` module, click on `Test Suites` then click on Add Custom Field.

Add the custom fields you would like displayed in the forms and tables. Set the options as required for each field, then click Update.

You can view the custom fields in the following forms, pages and tables:

* Create or Update a Test Case within Test Suites Module
* Viewing test cases on a test suite
* Viewing test cases on a project
* Viewing test cases in reports

## Project Test Case Custom Fields

From the `Administration` module, click on `Projects -> Test Cases` then click on Add Custom Field.

Add the custom fields you would like displayed in the forms and tables. Set the options as required for each field, then click Update.

You can view the custom fields in the following forms, pages and tables:

* Update a Test Case on a project
* Viewing test cases on a project
* Viewing test cases in reports

## Reporting Custom Fields

From the `Administration` module, click on `Projects -> Reporting` then click on Add Custom Field.

Add the custom fields you would like displayed in the forms and tables. Set the options as required for each field, then click Update.

You can view the custom fields in the following forms and pages:

* Reporting section on a project
* Viewing reporting fields in reports

## Summary Page Custom Fields

From the `Administration` module, click on `Projects -> Pages` then click on Add Custom Field.

Add the custom fields you would like displayed in the forms and tables. Set the options as required for each field, then click Update.

You can view the custom fields in the following forms and pages:

* Summary page on a project
* Viewing summary page fields in reports

## Group Custom Fields

From the `Administration` module, click on `Groups` then click on Add Custom Field.

Add the custom fields you would like displayed in the forms and tables. Set the options as required for each field, then click Update.

You can view the custom fields in the following forms and pages:

* Viewing a group within the Groups module

## Linked Project Key

When setting up your project request custom fields & project custom fields, you may wish to have come data from the project request captured and stored on the project as well. This can be achieved using the Linked Project Key on the Project Request custom fields.

The following example will:&#x20;

* create a custom field on Projects to capture project status notes "project\_notes".&#x20;
* create a custom field on Project Requests to capture additional notes from the customer "customer\_notes".
* Map the additional notes from the customer "customer\_notes" to the project status notes "project\_notes" when the request is getting approved and project is getting set up.

#### Step 1:  Create a custom field for Projects "project\_notes"

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FZQigvkNO6pPNQyQ74uPG%2F1.png?alt=media&#x26;token=12f0c70e-70af-4124-8bf0-a0ba30bd30f8" alt=""><figcaption></figcaption></figure>

#### Step 2: Create a custom field for Project Requests "customer\_notes" and link the Project custom field

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2Fr89IOZ34nsBQLTZnRy4R%2F2.png?alt=media&#x26;token=b1324cc9-2635-4059-b27e-f1d87d93d7c2" alt=""><figcaption></figcaption></figure>

#### Step 3: Create a new Project Request. Observe the new Additional Notes field

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FcUUDKCkGwfGjjTCmxoid%2F3.png?alt=media&#x26;token=d1e6982d-5534-4b3b-9713-34eef466d511" alt=""><figcaption></figcaption></figure>

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2F1Sw8byqjKSMvNNdT8Rtr%2F4.png?alt=media&#x26;token=9f1db609-feba-495c-a2a5-50ac3c2bcbfc" alt=""><figcaption></figcaption></figure>

#### Step 4: Approve the Project Request and observe the Project Notes field has the data from the customer's Additional Notes field.

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FGKBjytG76pRmAq2uH1ii%2F5.png?alt=media&#x26;token=2dfa6c65-a8e5-40cf-a261-583192d570ac" alt=""><figcaption></figcaption></figure>

## Using Custom Fields with APIs

You can create and update custom fields using the Self-Service APIs and the import vulnerabilities application API.&#x20;

> Custom fields do not need to be configured in the administration settings in order to be created or updated via the APIs. However, if the custom field Key matches one that is already defined in the admin settings, it will be automatically typed to that setting when presented in the user interface.

When importing custom fields, you must supply a Key and a Value for each custom field as follows:

<pre class="language-json"><code class="lang-json"><strong>"custom_fields": [
</strong><strong>    {
</strong><strong>         "key": "something",
</strong><strong>         "value": "some value..."           
</strong><strong>    }
</strong><strong>]
</strong></code></pre>

The Key must meet the following conditions:

* is lowercase letters, uppercase letters, numbers or underscores.
* cannot start with underscore.

The Value must meet the following conditions:

* is String, String Array, or Array of Objects

### String

Strings are used to store data for **Input**, **Text Area**, **Date-picker**, **Rich-Text** and **Select** fields.

An example of a custom field with a string is as follows:

<pre class="language-json"><code class="lang-json"><strong>"custom_fields": [
</strong><strong>    {
</strong><strong>         "key": "something",
</strong><strong>         "value": "...lorem ipsum..."           
</strong><strong>    }
</strong><strong>]
</strong></code></pre>

If intending to use the data for a Date-picker, you must supply it as a UTC string e.g. 2021-06-03T23:15:33.008Z

<pre class="language-json"><code class="lang-json"><strong>"custom_fields": [
</strong><strong>    {
</strong><strong>         "key": "something",
</strong><strong>         "value": "2021-06-03T23:15:33.008Z"           
</strong><strong>    }
</strong><strong>]
</strong></code></pre>

### String Array (string\[])

String Arrays are used to store data for **Multi-Select, User Select, User Multi-Select, Group Select, Group Multi-Select** fields.

An example of a custom field with a string array is as follows:

<pre class="language-json"><code class="lang-json"><strong>"custom_fields": [
</strong><strong>    {
</strong><strong>         "key": "something",
</strong><strong>         "value": [
</strong><strong>              "hello",
</strong><strong>              "goodbye"
</strong><strong>         ]          
</strong><strong>    }
</strong><strong>]
</strong></code></pre>

### Array of Objects

Array of Objects are used to store data in tabular format for **Table** fields.&#x20;

Every object is considered a *row of data.*&#x20;

Every key in the object is considered a *column of data*.&#x20;

Therefore a 2x2 table:

| column1 | column2 |
| ------- | ------- |
| hello   | goodbye |
| goodbye | hello   |

Can be represented as follows:

<pre class="language-json"><code class="lang-json"><strong>"custom_fields": [
</strong><strong>    {
</strong><strong>         "key": "table1",
</strong><strong>         "value": [
</strong><strong>              {
</strong><strong>                   "column1": "hello",
</strong><strong>                   "column2": "goodbye"
</strong><strong>              },
</strong><strong>              {
</strong><strong>                   "column1": "goodbye",
</strong><strong>                   "column2": "hello"
</strong><strong>              }
</strong><strong>         ]          
</strong><strong>    }
</strong><strong>]
</strong></code></pre>

The objects must have a Key and Value.

The Key must meet the following conditions:

* is lowercase letters, uppercase letters, numbers or underscores.
* cannot start with underscore.

The Value must meeting the following conditions:

* is String or String Array

<pre class="language-json"><code class="lang-json"><strong>"custom_fields": [
</strong><strong>    {
</strong><strong>         "key": "something",
</strong><strong>         "value": [
</strong><strong>              {
</strong><strong>                   "column1": "...lorem ipsum...",
</strong><strong>                   "column2": [
</strong><strong>                        "hello",
</strong><strong>                        "goodbye"
</strong><strong>                   ]
</strong><strong>              }
</strong><strong>         ]          
</strong><strong>    }
</strong><strong>]
</strong></code></pre>

### Deleting Custom Fields

You can also delete a custom field by passing **null** to the Value as follows:

<pre class="language-json"><code class="lang-json"><strong>"custom_fields": [
</strong><strong>    {
</strong><strong>         "key": "something",
</strong><strong>         "value": null           
</strong><strong>    }
</strong><strong>]
</strong></code></pre>

## Custom System Fields

You can set custom fields for well-known system fields which provide additional functionality in AttackForge.

## Sys Field - Template POC

The following system field can be used to create a template steps to reproduce / proof of concept that will be automatically copied to the POC field when creating a new vulnerability.

* **Vulnerability Library Custom Field - af\_sys\_steps\_to\_reproduce**

To set up this custom system field, go to `Administration -> Writeups -> Custom Fields` and create a Text Area field with a key `af_sys_steps_to_reproduce`

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FkfgZhxWSV1Pdo5ogm8I4%2FScreenshot%202024-06-20%20at%209.25.50%E2%80%AFPM.png?alt=media&#x26;token=0a992695-8a2b-4108-8899-cd37b2dbaa78" alt=""><figcaption></figcaption></figure>

Now when that writeup is selected when adding a new vulnerability on a project, the template steps to reproduce / proof of concept will be automatically copied to the Steps to Reproduce field.

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FJGGYPoXNfC2E7pTl0Lx5%2FScreenshot%202024-06-20%20at%209.26.20%E2%80%AFPM.png?alt=media&#x26;token=4f2869d3-1a1d-45d1-996a-524e711fdc51" alt=""><figcaption></figcaption></figure>