Kenna Data Importer (JSON Connector)

Kenna Data Importer is a standard format format for bringing vulnerability data into the platform. It is a collection of assets and their vulns/findings, as well as vulnerability definitions for those vulns/findings. 

Setting up a KDI Connector via the UI

 See the section below on how to generate a KDI formatted file. Once that's done, here's the process to upload via UI: 

 
1) Log into the instance as an administrator
2) Create a new KDI connector by browsing to "Connectors" -> "Kenna Data Importer"
 
3) Use the "Upload and Run" button to select the JSON file and upload
4) Wait a minute or two while the file is uploaded. if you get a failure message, it'll be stored in the connector's page. 
5) When uploaded, you'll see the assets and vulnerabilities begin to populate!
6) To upload the file via the API, get the Connector ID for you new connector by clicking on the connector name. 
Screen_Shot_2020-08-28_at_8.42.15_AM.png
 

KDI JSON FORMAT 

Field Definitions

+ at least one required
* required field
** conditionally required

{
  "skip_autoclose"boolean,  *
  "reset_tags"boolean,
  "assets":[  *
    {
      "file": string,  + (At least one of the fields with a + is required for each asset.)
      "ip_address": string, + (See help center or support for locator order set for your instance)
      "mac_address": string, +
      "hostname": string, +
      "ec2": string, +
      "netbios": string, +
      "url": string, +
      "fqdn": string, +
      "external_id": string, +
      "database": string, +
      "application": string **, (This is the app identifier and is required if url or file are used as locators)
      "tags": [
        string (Multiple tags should be listed and separated by commas)
      ],
      "owner": string,
      "os": string, (although not required, it is strongly recommended to populate this field when available)
      "os_version": string,
      "priority": integer, (defaults to 10, between 0 and 10 but default is recommended unless you have a documented risk appetite for assets)
      "vulns":[ * (If an asset contains no open vulns, this can be an empty array, but to avoid vulnerabilities from being closed, use the skip-autoclose flag)
        {
          "scanner_identifier": string, * (each unique scanner identifier will need a corresponding entry in the vuln-defs section below, this typically should be the external identifier used by your scanner)
          "scanner_type": string, * (required)
          "scanner_score": integer (between 0 and 10),
          "created_at": string, (iso8601 timestamp - defaults to current date if not provided)
          "last_seen_at": string, * (iso8601 timestamp)
          "last_fixed_on": string, (iso8601 timestamp)
          "closed_at": string, ** (required with closed status - This field used with status may be provided on remediated vulns to indicate they're closed, or vulns that are already present in Kenna but absent from this data load, for any specific asset, will be closed via our autoclose logic)
          "status": string, * (required - valid values open, closed)
          "port": integer,
        }
      ],
    }
  ],
      "findings":[ *
        {
          "scanner_type": string, * (required)
          "scanner_identifier": string, * (each unique scanner identifier will need a corresponding entry in the vuln-defs section below,thistypically should be the external identifier used by your scanner)
          "created_at": iso8601 timestamp string indicating when finding was first found by scanner - defaults to current dateifnot provided),
          "due_date":iso8601 timestamp string indicating when finding is due to be remediated),
          "last_seen_at":iso8601 timestamp string indicating when finding was last observed),
          "severity": integer (between 1 and 10),
          "triage state": string (new, in_progress, triaged, resolved, false_positive, risk_accepted, duplicate, not_a_security_issue), skip_autoclose is set to false, open vulns that already exist in Kenna will be closed if this field changes status to resolved. This field defaults to new if no status is provided.
          "additional_fields": array of hash objects with the field name being the key and value being the desired information to pass any scanner-specific fields about the finding,
        }
      ],
  "vuln_defs":[ * (This section is required for mapping findings from various scanners into canonical CVE or CWE findings / vulnerabilities in Kenna.)
    {
      "scanner_identifier": string, * (entry for each scanner identifier that appears in the vulns section, this typically should be the external identifier used by your scanner and matches entry in vulns/findings section. 
      "scanner_type": string, * (matches entry in vulns/findings section)
      "cve_identifiers": string, (note that this can be a comma-delimited list format CVE-000-0000)
      "wasc_identifiers": string, (note that this can be a comma-delimited list - format WASC-00)
      "cwe_identifiers": string, (note that this can be a comma-delimited list - format CWE-000)
      "name": string **, (title or short name of the vuln, will be auto-generated if not set) and used as the vuln/finding display value if cve/cwe/wasc not provided
      "description": string, (full description of the vuln)
      "solution": string, (steps or links for remediation teams)
    }
  ]
}

KDI JSON Field Descriptions

 

Field Documentation Key:

  1. * These fields are required
  2. + One or more of this group of fields is required
  3. ** These fields are conditionally required
Top-Level Configuration
  • skip_autoclose * - This boolean is used to determine if payload should trigger closing of existing vulnerabilities, if they exist in this payload.
    • Defaults to false because autoclose is generally desired. As an example, one would set this to true if uploading a file containing only "assets" with no vulns, in order to avoid all existing vulns from being closed.
  • reset_tags - This boolean is used to determine if ALL tags should be wiped from an asset before the tags defined in the KDI upload files are applied. 
    • As an example, set this parameter to true if tags frequently change for a KDI asset
    • Tags are additive-only if this parameter is not listed in the KDI or if it is set to false. 
    • Caution: If set to true, all tags will be removed from the matching asset regardless of source. If an asset has tags both from a KDI and scanner connector, the scanner connector would need to run again before the scanner tags would be regenerated. 

 

Asset Section  ( "assets" section ) 

Asset Locator Fields - These fields are used as locators, and at least one of these is required. 

  • file + - path to affected file
  • ip_address + - IP of internal facing asset
  • mac_address + - MAC address asset
  • hostname + - host name/domain name of affected asset
  • ec2 + - Amazon EC2 instance id or name
  • netbios + - netbios name
  • url + - URL pointing to asset
  • fqdn + - FQDN of asset
  • external_id + - External ID of asset - This is often used as an internal organizational tracking name for the asset
  • database + - Name of database
  • application ** - identifier/name of app from scanner perspective - This field is required is using url or file for the primary locator. This field allows finding to be assigned to Applications in Kenna. 

Asset Metadata Fields 

  • tags - list of strings that correspond to tags on an asset
  • owner - Some string that identifies an owner of an asset
  • os - Operating system of asset
  • os_version - Version of asset's operating system
  • priority - Priority (or value) of asset (integer 0 to 10). This field is used to adjust asset score. Default is 10.
Vulnerability Section ( "vuln" section underneath an individual "asset" )
  • scanner_type * - Some string that identifies the type of scanner data is coming from
  • scanner_identifier * - Some string that is used to identify the unique data coming in from the scanner named in scanner_type
  • details - Details about how to reproduce vuln
  • created_at - DateTime string indicating when vulnerability was first found by scanner
    Important: The created_at field maps to found_on to provide the actual date the vulnerability was first found by the scanner.
  • scanner_score - score between 1 and 10 given by scanner
  • last_fixed_on - DateTime string indicating when vuln was last fixed
  • last_seen_at - DateTime string indicating when vuln was last observed
  • status * - status of vuln remediation ("open or closed"), skip_autoclose is set to false, open vulns that already exist in Kenna will be closed if this field changes their status to closed.
  • closed_at - DateTime string indicating when vuln was closed
  • port - Port that vuln is referring to
Findings Section ( "findings" section underneath an individual "asset" )
  • scanner_type* - Some string that identifies the type of scanner data is coming from
  • scanner_identifier * - Some integer that is used to identify the unique data coming in from the scanner named in scanner_type
  • created_at - DateTime string indicating when vulnerability was first found by scanner
    Important: The created_at field maps to found_on to provide the actual date the vulnerability was first found by the scanner.
  • due_date - DateTime string indicating when finding is due to be remediated
  • last_seen_at - DateTime string indicating when finding was last observed
  • severity - score between 1 and 10 given by scanner
  • triage_state  - status of the finding (
    "new, in_progress, triaged, resolved, false_positive, risk_accepted, duplicate, not_a_security_issue"). Status resolved and/or findings missing from the report, will be set to resolved (closed) in Kenna if skip_autoclose is set to false. If skip_autoclose is set to true only explicit value changes in using this field will be applied. 
  • additional_fields - An array of fieldname/value pairs being the desired information to pass any scanner specific fields about the finding.
Vulnerability Definition Section ( "vuln_defs" section of the JSON )
  • scanner_type * - Some string that identifies the type of scanner data is coming from
  • scanner_identifier * - some string that is used to identify the unique data coming in from the scanner named in scanner_type
  • cve_identifiers - Comma separated string of CVE Identifiers
  • wasc_identifiers - string of a wasc identifier
  • cwe_identifiers - string of a cwe indentifier
  • name ** - Name of a vulnerability identified by scanner - required if all "identifiers" fields are blank. 
  • description - short description of vulnerability identified in by scanner - include node only if not null. 
  • solution - solution of vulnerability identified by scanner - include node only if not null.

Examples:

Here is an example of a minimal generated KDI file that is ready for import into the Kenna platform. 

{

  "skip_autoclose": false,
  "assets": [
  {
    "url": "www.myco.com",
    "tags": [
    "AppID:DES",
    "Find_type:Internal Reporter"
    ],
    "vulns": [],
    "findings": [
    {
      "scanner_type": "PenTestA",
      "scanner_identifier": "PSRC-7783",
      "created_at": "2020-06-12-00:00:00",
      "severity": 3,
      "last_seen_at": "2020-06-27-12:19:18",
      "triage_state": "new",
      "additional_fields": {
        "line_number": "156",
        "source_file": "testfolder/testfile.rb"
      }
    }
    ]
  },
  {
    "ec2": "i-02aadcccfda719968",
    "ip_address": "172.31.42.121",
    "priority": 9,
    "tags": [
      "AWS"
    ],
    "vulns": [
    {
      "scanner_type": "AWS Inspector",
      "scanner_identifier": "aws-vuln-id-1",
      "created_at": "2018-11-10-18:08:57",
      "last_seen_at": "2018-11-10-18:08:57",
      "status": "open"
    },
    {
      "scanner_type": "AWS Inspector",
      "scanner_identifier": "aws-vuln-id-2",
      "created_at": "2018-11-10-18:08:57",
      "last_seen_at": "2018-11-10-18:08:57",
      "status": "open"
    },
    {
      "scanner_type": "AWS Inspector",
      "scanner_identifier": "aws-vuln-id-3",
      "created_at": "2018-11-10-18:08:57",
      "details": "some details about how CVE-2018-10853 and CVE-2018-18074 are impacting asset",
      "last_seen_at": "2018-11-10-18:08:57",
      "status": "open"
    }
    ]
  }
  ],

  "vuln_defs": [
  {
    "scanner_identifier": "aws-vuln-id-1",
    "scanner_type": "AWS Inspector",
    "cve_identifiers": "CVE-2018-17456",
    "name": "Name of vulnerability involving CVE-2018-17456",
    "description": "Description of vuln involving CVE-2018-17456",
    "solution": "Do something good to fix CVE-2018-17456"
  },
  {
    "scanner_identifier": "aws-vuln-id-2",
    "scanner_type": "AWS Inspector",
    "cve_identifiers": "CVE-2018-6555",
    "name": "Name of vulnerability involving CVE-2018-6555",
    "description": "Description of vuln involving CVE-2018-6555",
    "solution": "Do something good to fix CVE-2018-6555"
  },
  {
    "scanner_identifier": "aws-vuln-id-3",
    "scanner_type": "AWS Inspector",
    "cve_identifiers": "CVE-2018-10853, CVE-2018-18074",
    "name": "Name of vulnerability involving CVE-2018-10853, CVE-2018-18074",
    "description": "Description of vuln involving CVE-2018-10853, CVE-2018-18074"
  },
  {
    "scanner_identifier": "PSRC-7783",
    "scanner_type": "PenTestA",
    "cwe_identifiers": "CWE-200",
    "name": "Name of vulnerability involving CWE-200",
    "description": "Description of vuln involving CWE-200"
  }
  ]
}

Powered by Zendesk