Skip to content
This repository has been archived by the owner on Sep 1, 2019. It is now read-only.

Security Tool Automation Docs & Examples

Jump to bottom
Steve Springett edited this page Jul 25, 2017 · 3 revisions

Automating the execution of security tools has been simplified and standardized using Hakbot Origin Controller. Regardless of the scanner used, the process of performing the automation is identical. Only minor differences exist in the provider-specific payloads.

REST Documentation

Hakbot Origin Controller leverages Swagger 2.0 to provide API documentation along with an end-user interface that allows users to view API documentation and interact with the API.

  • http://{hostname}/{context}/api/swagger.json

The documentation covers nearly all cases, however, due to minor differences in how each provider and publisher operates, these could not be documented in a standardized way. Therefore, this wiki will provide concrete payload examples for each provider and publisher.

Format Syntax

{
  "name": "Name of the job (required)",
  "provider": {
    "class": "io.hakbot.providers.somescanner.ScannerProvider",
    "payload": {
      "plugin-specific-param #1": "my value",
      "plugin-specific-param #1": "my value"
    }
  },
  "publisher": {
    "class": "io.hakbot.publishers.mypub.MyPublisher",
    "payload": {
      "plugin-specific-param #1": "my value",
      "plugin-specific-param #1": "my value"
    }
  }
}

All jobs require the name parameter to be specified along with a provider. The provider in turn, requires the fully qualified classname and a payload. Payloads are plugin specific - they will vary based on the specific implementation of the provider or publisher. Jobs may optionally contain a publisher object. Publishing is completely optional, but recommended for Continuous Security or Continuous Delivery pipelines.

Instances

Most providers and publishers leverage 'instances'. Instances are defined in application.properties and may define the following:

  • Alias - a human readable name that can be used to refer to specific instances
  • URL - The URL to the instance
  • Username - The username to used to login to the instance
  • Password - The password to used to login to the instance
  • API Key - The API Key used for authentication to the instance
  • Token - The token used for authentication to the instance

Automating Using an Instance Definition

{
  "name": "Name of the job (required)",
  "provider": {
    "class": "io.hakbot.providers.somescanner.ScannerProvider",
    "payload": {
      "instance": "DevOps Team",
      "plugin-specific-param #1": "my value",
      "plugin-specific-param #2": "my value"
    }
  }
}

By defining an instance, we don't have to worry about hostnames, URLs, or authentication, as these are resolved for you automatically by the controller. The advantage of this approach is centralized control over these parameters which can greatly reduce maintenance in the event of changes to the environment, as well as not exposing potentially sensitive credentials. The drawback is that there is no way to guarantee that only persons you want to use a given instance actually do, as access to resolve the instances do not require authorization. In general, for a tightly controlled CS/CD environment, taking advantage of instances will save countless hours in maintenance.

The following concrete examples do not specify instances, although they can be specified in place of URLs and credentials.

Automating Nessus Scans

{
  "name": "Test Scan",
  "provider": {
    "class": "io.hakbot.providers.nessus.NessusProvider",
    "payload": {
      "url": "https://nessus.example.com:8834",
      "username": "myusername",
      "password": "mypassword",
      "scanName": "My Scan",
      "scanPolicy": "My Policy",
      "targets": "target1.example.com,target2.example.com"
    }
  }
}

Automating AppSpider Pro Scans

{
  "name": "Test Scan",
  "provider": {
    "class": "io.hakbot.providers.appspider.AppSpiderProvider",
    "payload": {
      "url": "http://hostname/AppSpiderEntScanEngine/default.asmx?WSDL",
      "username": "AppSpider",
      "password": "Se!",
      "scanConfig": "{Base64 encoded *.scfg file}"
    }
  }
}

AppSpider Pro requires a scan config be specified. The scan config must be Base64 encoded and send as the value of the scanConfig property.

Publishing Results to the Filesystem

"publisher": {
  "class": "io.hakbot.publishers.filesystem.FileSystemPublisher",
  "payload": {
    "publishPath": "/Users/steve/Desktop"
  }
}

When this optional publisher object is specified as part of the job creation request, the result generated by the job will be written to the specified publishPath using the UUID of the job.

Publishing Results to ThreadFix

"publisher": {
  "class": "io.hakbot.publishers.threadfix.ThreadFixPublisher",
  "payload": {
    "url": "http://hostname/threadfix/rest",
    "apikey": "1234567890ABCD",
    "appId": "100"
  }
}

When this optional publisher object is specified as part of the job creation request, the result generated by the job will be uploaded to ThreadFix to the application having the specified appId. URLs with API key or username/password combinations are permitted, as well as use of instance definitions.

Publishing Results to KennaSecurity

"publisher": {
  "class": "io.hakbot.publishers.kennasecurity.KennaSecurityPublisher",
  "payload": {
    "url": "https://api.kennasecurity.com/connectors/1/data_file",
    "token": "1234567890ABCD"
  }
}

When this optional publisher object is specified as part of the job creation request, the result generated by the job will be uploaded to KennaSecurity. Use of urls with tokens, or instance definitions are permitted.

Clone this wiki locally