Verification Connections

Get All Verification Connectors

Returns a list of all verification connectors available.

GET /api/v2/connectors/analysis/

GET /api/v2/connectors/analysis/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 1,
        "name": "Fortify Connector",
        "system": {
            "verification_categories": ["SAST", "DAST"],
            "id": "fortify",
            "short_name": "Fortify",
            "name": "Fortify Software Security Center"
        },
        "inaccessible": false
    }]
}

Get a Specific Verification Connector

Returns a specific verification connector.

GET /api/v2/connectors/analysis/{id}/

GET /api/v2/connectors/analysis/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "name": "Fortify Connector",
    "system": {
        "verification_categories": ["SAST", "DAST"],
        "id": "fortify",
        "short_name": "Fortify",
        "name": "Fortify Software Security Center"
    },
    "inaccessible": false
}

Get Custom Countermeasure Mapping File for Verification Connector

Returns the custom countermeasure mapping file associated with the connector.

GET /api/v2/connectors/analysis/{id}/mapping/

GET /api/v2/connectors/analysis/1/mapping/ HTTP/1.1
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: text/csv

Task ID,Task Title,Weakness ID,Weakness Title,Confidence,CWE
T186,Use recommended settings and the latest patches for third party libraries and software,HiveMailXSS,HiveMail index.php Cross-Site Scripting,low,
T186,Use recommended settings and the latest patches for third party libraries and software,AdvancedGuestbookpicturephpXSS,Advanced Guestbook picture.php Cross-Site Scripting,low,
T186,Use recommended settings and the latest patches for third party libraries and software,WordpressPageFlipImageGalleryPlugingetConfigphpPathTraversal,Wordpress Page Flip Image Gallery Plugin getConfig.php Path Traversal,low,
T186,Use recommended settings and the latest patches for third party libraries and software,TPHidden_OWB_ABAP_Info_Usage_SYSYSID,ABAP Info Usage SYSYSID,low,
T186,Use recommended settings and the latest patches for third party libraries and software,CrossSiteScriptingThroughFlash,Cross-Site Scripting through Flash (ActionScript 2),low,
T186,Use recommended settings and the latest patches for third party libraries and software,PHPphpinfoXSS2,PHP phpinfo() Cross-Site Scripting (Versions 4.4.3 - 4.4.6),low,
T186,Use recommended settings and the latest patches for third party libraries and software,attMicrosoftSiteServerSampleScriptSQLVulnerability,Microsoft Site Server Sample Script SQL Injection,low,
T186,Use recommended settings and the latest patches for third party libraries and software,BLOGCMSMultipleRFI,BLOG:CMS Multiple Remote File Inclusion,low,
T186,Use recommended settings and the latest patches for third party libraries and software,WordPressFeedListPluginhandlerimagephpXSS,WordPress FeedList Plugin handler_image.php Cross-Site Scripting,low...

Create a Verification Connector

Fields Required Description
name Yes The name of the new connector.
system Yes A dictionary identifying the system, containing its id. For example: {"id": "checkmarx"}.
inaccessible No Specifies whether the Issue Tracker server specific is accessible from the SDE server. Defaults to false.
params Yes A dictionary containing connections options. Please refer to product documentation for more details or reach out to support. Required params will return appropriate errors when unspecified. 
POST /api/v2/connectors/analysis/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "name": "Example Verification Connector",
    "system": {
        "id": "checkmarx"
    },
    "inaccessible": false,
    "params": {
        "analysis_method": "https",
        "analysis_validate_cert": true,
        "analysis_server": "server.com",
        "analysis_context_root": "",
        "analysis_auth_mode": "basic",
        "analysis_user": "user",
        "analysis_pass": "pass"
    }
}

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 1,
    "name": "Example Verification Connector",
    "system": {
        "id": "checkmarx",
        "short_name": "Checkmarx",
        "name": "Checkmarx"
    },
    "inaccessible": false,
    "params": {
        "analysis_auth_mode": "basic",
        "analysis_user": "user",
        "analysis_validate_cert": true,
        "analysis_pass": "pass",
        "analysis_method": "https",
        "analysis_server": "server.com",
        "integration_mode": "api"
    }
}

Create a Custom Countermeasure Mapping File for Verification Connector

Fields Required Description
custom_task_mapping_file Yes The custom countermeasure mapping file 
PUT /api/v2/connectors/analysis/1/mapping/ HTTP/1.1
Content-type: multipart/form-data
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 201 CREATED

Update a Verification Connector

Updates a specific Verification connector resource as specified by the connector id.

PATCH /api/v2/connectors/analysis/{id}

PATCH /api/v2/connectors/analysis/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "name": "Example PATCH Verification Connector",
    "system": {
        "id": "checkmarx"
    },
    "inaccessible": false,
    "params": {
        "analysis_method": "https",
        "analysis_validate_cert": true,
        "analysis_server": "server.com",
        "analysis_context_root": "",
        "analysis_auth_mode": "basic",
        "analysis_user": "user",
        "analysis_pass": "pass"
    }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "name": "Example Verification Connector",
    "system": {
        "id": "checkmarx",
        "short_name": "Checkmarx",
        "name": "Checkmarx"
    },
    "inaccessible": false,
    "params": {
        "analysis_auth_mode": "basic",
        "analysis_user": "user",
        "analysis_validate_cert": true,
        "analysis_pass": "pass",
        "analysis_method": "https",
        "analysis_server": "server.com",
        "integration_mode": "api"
    }
}

Delete a Custom Countermeasure Mapping File for Verification Connector

Deletes the custom countermeasure mapping file associated with the connector.

DELETE /api/v2/connectors/analysis/{id}/mapping/

DELETE /api/v2/connectors/analysis/1/mapping/ HTTP/1.1
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 204 NO CONTENT

Get All Verification Connections of All Projects

Returns a list of all Verification connections associated with all projects. The params are only displayed if you have the 'Edit verification connections' permission.

The parameter last_successful_run only appears if the Verification connection has at least one successful sync.

GET /api/v2/connections/analysis/

Query Parameters

The following parameters may be used to filter the Verification connections resources in the response.

Parameter Description
project Returns all Verification connections for the project with the specified id. 
GET /api/v2/connections/analysis/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 1,
        "connector": 1,
        "project": 1,
        "system": {
            "verification_categories": ["SAST", "DAST"],
            "id": "whitehat",
            "short_name": "WhiteHat",
            "name": "WhiteHat Sentinel"
        },
        "alias": "WhiteHat Integration",
        "frequency": "manually",
        "command": "sync_whitehat",
        "debug_mode": false,
        "params": {
            "asset_name": "WebGoat Java",
            "sde_project": "WhiteHat",
            "sde_businessunit": "General",
            "sde_application": "Demo Application",
            "import_behaviour": "replace-scanner",
            "analysis_server": "server.whitehatsec.com",
            "task_status_mapping": "{}",
            "last_successful_run": "2019-11-28T20:22:32.588388+00:00"
        },
        "inaccessible": false,
        "is_file_upload": false
    }]
}

Include Parameters

See the Include Parameters section for more details.

Parameter Description
last_job Include the details of the last job executed for this connection. 
GET /api/v2/connections/analysis/?include=last_job HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "id": 1,
        "connector": 1,
        "project": 1,
        "system": "WhiteHat",
        "alias": "WhiteHat Integration",
        "frequency": "manually",
        "command": "sync_whitehat",
        "debug_mode": false,
        "params": {
            "asset_name": "WebGoat Java",
            "sde_project": "WhiteHat",
            "sde_businessunit": "General",
            "sde_application": "Demo Application",
            "import_behaviour": "replace-scanner",
            "analysis_server": "server.whitehatsec.com",
            "last_successful_run": "2019-11-28T20:22:32.588388+00:00"
        },
        "inaccessible": false,
        "last_job": {
            "id": 4,
            "last_run": "2016-12-15T22:45:27.412Z",
            "automatic": false,
            "ready": true,
            "result_message": "Error Message",
            "succeeded": false,
            "user": 3,
            "triggered_by": 1
        },
        "is_file_upload": false
    }]
}

Get a Specific Verification Connection

Returns a specific verification connection. The params are only displayed if you have the 'Edit verification connections' permission.

GET /api/v2/connections/analysis/{connection_id}/

GET /api/v2/connections/analysis/{connection_id}/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "connector": 1,
    "project": 1,
    "system": {
        "verification_categories": ["SAST", "DAST"],
        "id": "whitehat",
        "short_name": "WhiteHat",
        "name": "WhiteHat Sentinel"
    },
    "alias": "WhiteHat Integration",
    "frequency": "manually",
    "command": "sync_whitehat",
    "debug_mode": false,
    "params": {
        "asset_name": "WebGoat Java",
        "sde_project": "WhiteHat",
        "sde_businessunit": "General",
        "sde_application": "Demo Application",
        "import_behaviour": "replace-scanner",
        "analysis_server": "server.whitehatsec.com"
    },
    "inaccessible": false,
    "is_file_upload": false
}

Create a Verification Connection

Only remote verification connections can be created via the api.

Fields Required Description
alias No The name of the new connection. Will default to the name of the connector.
connector Yes The id of the connector that this connection will use to connect with the Verification Tool.
project Yes The id of the SD Elements project that this connection will connect with.
frequency No The frequency in which this connection will sync. The available options for organizations with the advanced Issue Tracker feature are: "hourly", "daily", "weekly", "monthly" and "manually". If unspecified, the frequency will default to "manually". Organizations without the advanced Issue Tracker feature can only choose "manually".
params Yes A dictionary containing connections options. Please refer to product documentation for more details or reach out to support.
is_file_upload No An indication of whether the connection is a file upload or a remote connection. It is an error to create a new connection with this field set to "true", as this type can only be created indirectly with a file upload verification job. Defaults to "false." 
POST /api/v2/connections/analysis/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "alias": "Example Verification Connection",
    "connector": 2,
    "project": 1,
    "frequency": "daily",
    "debug_mode": true,
    "params": {
        "task_status_mapping_pass": "DONE",
        "import_behaviour": "combine",
        "project_name": "My project"
    },
    "is_file_upload": false
}

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 9,
    "connector": 2,
    "alias": "Example Verification Connection",
    "system": {
        "id": "veracode",
        "name": "Veracode"
    },
    "project": 1,
    "frequency": "daily",
    "command": "import_veracode",
    "debug_mode": true,
    "params":{
        "integration_mode": "api",
        "analysis_auth_mode": "basic",
        "analysis_user": "Code",
        "analysis_pass": "Name",
        "sde_businessunit": "BU",
        "sde_application": "Financial App",
        "sde_project": "Example Project",
        "analysis_server": "vera",
        "import_behaviour": "combine",
        "analysis_method": "http",
        "session_capture_socket": "/doc/sde/sdetools_session_capture.sock",
        "task_status_mapping_pass": "DONE",
        "project_name": "My project"
    },
    "inaccessible": false,
    "is_file_upload": false
}

Update a specific Verification Connection

Update a specific Verification Connection resource.

PATCH /api/v2/connections/analysis/{connection_id}/

URL Parameters

Parameter Description
connection_id The ID of the Verification Connection to update 
PATCH /api/v2/connections/analysis/2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "alias": "Example Verification Connection Updated Name",
    "connector": 2,
    "project": 1,
    "frequency": "hourly",
    "params": {}
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 9,
    "connector": 2,
    "alias": "Example Verification Connection Updated Name",
    "system": {
        "id": "veracode",
        "name": "Veracode"
    },
    "project": 1,
    "frequency": "hourly",
    "command": "import_veracode",
    "debug_mode": false,
    "params":{
        "integration_mode": "api",
        "analysis_auth_mode": "basic",
        "analysis_user": "Code",
        "analysis_pass": "Name",
        "sde_businessunit": "BU",
        "sde_application": "Financial App",
        "sde_project": "Example Project",
        "analysis_server": "vera",
        "import_behaviour": "replace-scanner",
        "analysis_method": "http"
    },
    "inaccessible": false,
    "is_file_upload": false
}

Test a Verification Connection

Performs a connectivity and credential check against the Verification Tool without running an import, and validates the rest of the connection configuration.

Only remote verification connections can be tested.

This endpoint requires the 'Edit verification connections' permission, or the 'Verify countermeasures' permission on the project named in the request.

POST /api/v2/connections/test-analysis/

Fields Required Description
connector Yes The id of the connector that holds the Verification Tool configuration to test.
project Yes The id of the SD Elements project that this connection would connect with.
params Yes A dictionary containing connections options. Please refer to product documentation for more details or reach out to support.
alias No The name of the connection. Will default to the name of the connector.
frequency No The sync frequency the connection would use. The available options are the same ones accepted when creating a connection.
id No The id of an existing verification connection. When supplied, the stored credentials are reused for any protected params omitted from the request. 
POST /api/v2/connections/test-analysis/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "connector": 2,
    "project": 1,
    "params": {
        "project_name": "My project"
    }
}

When the Verification Tool is reachable and the configuration is valid, the API returns HTTP 200:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true
}

When the Verification Tool is unreachable, rejects the credentials, or reports any other problem, the API still returns HTTP 200, with success set to false and an error string describing the failure:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": false,
    "error": "connection refused"
}

Connections whose Verification Tool does not support a connectivity check are reported the same way:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": false,
    "error": "Testing this connection is not yet available."
}

When the request itself is invalid, for example a missing required field, an unknown connector id, a connector that belongs to another organization, or a file upload connector, the API returns HTTP 400 with the field errors:

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json

{
    "connector": [
        "This field is required."
    ]
}

results matching ""

    No results matching ""