Proposing a Mitigation with the Annotations API

Veracode APIs

Use this command to propose a mitigation, based on an environmental control in the network, with a comment, for an application with two findings:

http --auth-type=veracode_hmac POST "https://api.veracode.com/appsec/v2/applications/{application_guid}/annotations" < input.json

You can use the Applications API to get the GUID for an application.

The API passes the JSON file that you populate with the necessary values as shown in this example payload:

{
  "issue_list": "1,2",
  "comment": "This is my comment",
  "action": "NETENV"
}

Proposing a Mitigation in TSRV Format

If you want to propose a mitigation with a comment in TSRV format:

  • Provide each Technique, Specifics, Remaining Risk, and Verification component in the comment as a single string
  • Separate each component with a carriage return and the line feed \r\n

For example, for a mitigation proposal with these TSRV components:

  • Technique : M1 : Establish and maintain control over all of your inputs.
  • Specifics : We are using an encoder for our input.
  • Remaining Risk : None.
  • Verification : We must decline, for secret reasons.

Add this value to the comment property in your payload:

{
  "issue_list": "1,2",
  "comment": "\rTechnique : M1 : Establish and maintain control over all of your inputs\r\nSpecifics : We are using an encoder for our input.\r\nRemaining Risk : None.\r\nVerification : We must decline, for secret reasons.",
  "action": "NETENV"
}

Note: These comments are only examples. Veracode does not recommend offering any of these comments in your mitigations.

Mitigation Properties

Name Type Description
issue_list
Required
String Comma-separated list of finding IDs. You can use the Findings API to get a list of finding IDs for an application.
comment
Required
String Enter a brief comment about the findings for issue_list.
action
Required
String Enter one of these mitigation actions:
  • APPDESIGN states that custom business logic within the body of the application has addressed the finding. An automated process may not be able to fully identify this business logic.
  • NETENV states that the network in which the application is running has provided an environmental control that has addressed the finding.
  • OSENV states that the operating system on which the application is running has provided an environmental control that has addressed the finding.
  • FP, which stands for false positive, states that Veracode has incorrectly identified a finding in your application. If you identify a finding as a potential false positive, Veracode does not exclude the potential false positive from your published report. Your organization can approve a potential false positive to exclude it from the published report. If your organization approves a finding as a false positive, your organization is accepting the risk that the finding might be valid.
  • LIBRARY states that the current team does not maintain the library containing the finding. You referred the vulnerability to the library maintainer.
  • ACCEPTRISK states that your business is willing to accept the risk associated with a finding. Your organization evaluated the potential risk and effort required to address the finding.