MSRC Public API - Testing

API change history

This RESTful API can be used to engage the Microsoft Security Response Center (MSRC) in the following ways:

  • Get security update summaries and details using the Common Vulnerability Reporting Framework (CVRF).

  • Report suspected cyberattacks or abuse originating from Microsoft Online Services.

  • Notify Microsoft of any planned penetration tests against your Azure assets.

Sample client code is available on the Microsoft Security Updates and Engage Github repositories.

Cars_PostCarsReport

Submit reports to Microsoft's Computer Emergency Response Team (CERT) using the Common Abuse Reporting System (CARS). This action is to report suspected cyberattacks or abuse originating from Microsoft Online Services, such as Azure, Bing, Outlook, OneDrive, and Office 365. This includes malicious network activity originating from Microsoft IP addresses. It also includes distribution of malicious content or other illicit material through Microsoft Online Services.

Try it

Request URL

Request parameters

(optional)
string

API version (yyyy)

Request headers

(optional)
string
Media type of the body sent to the API.
string
Subscription key which provides access to this API. Found in your Profile.
string
OAuth 2.0 access token obtained from Microsoft AAD - testing. Supported grant types: Authorization code.

Request body

CARS-formatted abuse report

{
  "testSubmission": true,
  "carsAdvancedCheck": true,
  "reporterInfo": {
    "reporterEmail": "someone@contoso.com",
    "reporterName": "First Last",
    "reporterPhone": "000-000-0000",
    "reporterOrg": "Contoso",
    "discloseEmail": "true",
    "reporterNotes": "This is example reporter information."
  },
  "reports": [
    {
      "report": {
        "batchID": "campaign X",
        "relatedCases": [
          "TODO"
        ],
        "reportNotes": "This is an example abuse report.",
        "tlp": "WHITE",
        "disclosureNotes": "Share freely.",
        "threats": [
          {
            "threat": {
              "threatType": "activity",
              "threatSubType": "spam",
              "sourceIp": "1.1.1.1",
              "destinationIp": "2.2.2.2",
              "sourcePort": "1",
              "destinationPort": "2",
              "protocol": "0",
              "byteCount": "1",
              "packetCount": "1",
              "date": "2000-01-20",
              "time": "00:00:00",
              "timeZone": "-00:00",
              "sample": "This is example activity threat information.",
              "sampleType": "text/plain"
            }
          },
          {
            "threat": {
              "threatType": "content",
              "threatSubType": "malware",
              "sourceUrl": "evil.com",
              "destinationUrl": "example.com",
              "protocol": "0",
              "date": "2000-01-20",
              "time": "00:00:00",
              "timeZone": "-00:00",
              "sample": "This is example content threat information.",
              "sampleType": "text/plain"
            }
          }
        ]
      }
    }
  ]
}
{
  "description": "a Common Abuse Reporting System (CARS) submission",
  "required": [
    "testSubmission",
    "reporterInfo",
    "reports"
  ],
  "type": "object",
  "properties": {
    "testSubmission": {
      "description": "is this a test submission? If so, the API will validate the input but won't submit it to MSRC for action",
      "type": "boolean"
    },
    "carsAdvancedCheck": {
      "description": "do the reports include detailed fields? This can be false only for form submissions (API users should ignore it)",
      "type": "boolean"
    },
    "reporterInfo": {
      "description": "information about the reporter (whoever is doing the submitting)",
      "required": [
        "reporterEmail",
        "reporterName",
        "discloseEmail",
        "reporterNotes"
      ],
      "type": "object",
      "properties": {
        "reporterEmail": {
          "description": "reporter email address, may be used for further correspondence",
          "type": "string"
        },
        "reporterName": {
          "description": "reporter name",
          "type": "string"
        },
        "reporterPhone": {
          "description": "reporter phone number",
          "type": "string"
        },
        "reporterOrg": {
          "description": "reporter organization",
          "type": "string"
        },
        "discloseEmail": {
          "description": "allow response organization to share reporter email with an external incident resolver as appropriate?",
          "type": "string"
        },
        "reporterNotes": {
          "description": "any other relevant information about the reporter or reporter organization",
          "type": "string"
        }
      }
    },
    "reports": {
      "description": "reports of abuse",
      "type": "array",
      "items": {
        "description": "abuse report",
        "required": [
          "report"
        ],
        "type": "object",
        "properties": {
          "report": {
            "description": "abuse report",
            "required": [
              "reportNotes",
              "threats"
            ],
            "type": "object",
            "properties": {
              "batchID": {
                "description": "tag and group reports",
                "type": "string"
              },
              "relatedCases": {
                "description": "IDs of known related cases",
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "reportNotes": {
                "description": "a brief summary of what occurred",
                "type": "string"
              },
              "TLP": {
                "description": "[Traffic Light Protocol](https://www.us-cert.gov/tlp) color (RED, AMBER, GREEN, or WHITE) to regulate the level of\r\ndisclosure",
                "type": "string"
              },
              "disclosureNotes": {
                "description": "any additional limits on disclosure",
                "type": "string"
              },
              "threats": {
                "description": "instances of abuse",
                "type": "array",
                "items": {
                  "description": "an instance of abuse",
                  "required": [
                    "threat"
                  ],
                  "type": "object",
                  "properties": {
                    "threat": {
                      "description": "an instance of abuse",
                      "required": [
                        "threatType",
                        "threatSubType",
                        "date",
                        "time",
                        "timeZone"
                      ],
                      "type": "object",
                      "properties": {
                        "threatType": {
                          "description": "threat type: activity or content",
                          "type": "string"
                        },
                        "threatSubType": {
                          "description": "threat subtype (depends on threat type)",
                          "type": "string"
                        },
                        "sourceIp": {
                          "description": "IP address sending unwanted traffic (required for activity threats)",
                          "type": "string"
                        },
                        "destinationIp": {
                          "description": "IP address receiving unwanted traffic (required for activity threats)",
                          "type": "string"
                        },
                        "sourcePort": {
                          "description": "port sending unwanted traffic",
                          "type": "string"
                        },
                        "destinationPort": {
                          "description": "port receiving unwanted traffic",
                          "type": "string"
                        },
                        "sourceUrl": {
                          "description": "URL hosting abusive content (required for content threats)",
                          "type": "string"
                        },
                        "destinationUrl": {
                          "description": "URL receiving abusive content (required for content threats)",
                          "type": "string"
                        },
                        "protocol": {
                          "description": "[internet protocol number](http://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml) of the protocol being used to send or serve abusive traffic or data",
                          "type": "string"
                        },
                        "byteCount": {
                          "description": "total number of bytes received for reported traffic (activity threats only)",
                          "type": "string"
                        },
                        "packetCount": {
                          "description": "total number of packets received for reported traffic (activity threats only)",
                          "type": "string"
                        },
                        "date": {
                          "description": "date of abuse",
                          "type": "string"
                        },
                        "time": {
                          "description": "time of abuse",
                          "type": "string"
                        },
                        "timeZone": {
                          "description": "reporter time zone",
                          "type": "string"
                        },
                        "sample": {
                          "description": "sample data/artifacts relating to abuse",
                          "type": "string"
                        },
                        "sampleType": {
                          "description": "[Media Type](https://www.iana.org/assignments/media-types/media-types.xhtml) of sample (required if sample is provided)",
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "example": {
    "testSubmission": true,
    "carsAdvancedCheck": true,
    "reporterInfo": {
      "reporterEmail": "someone@contoso.com",
      "reporterName": "First Last",
      "reporterPhone": "000-000-0000",
      "reporterOrg": "Contoso",
      "discloseEmail": "true",
      "reporterNotes": "This is example reporter information."
    },
    "reports": [
      {
        "report": {
          "batchID": "campaign X",
          "relatedCases": [
            "TODO"
          ],
          "reportNotes": "This is an example abuse report.",
          "tlp": "WHITE",
          "disclosureNotes": "Share freely.",
          "threats": [
            {
              "threat": {
                "threatType": "activity",
                "threatSubType": "spam",
                "sourceIp": "1.1.1.1",
                "destinationIp": "2.2.2.2",
                "sourcePort": "1",
                "destinationPort": "2",
                "protocol": "0",
                "byteCount": "1",
                "packetCount": "1",
                "date": "2000-01-20",
                "time": "00:00:00",
                "timeZone": "-00:00",
                "sample": "This is example activity threat information.",
                "sampleType": "text/plain"
              }
            },
            {
              "threat": {
                "threatType": "content",
                "threatSubType": "malware",
                "sourceUrl": "evil.com",
                "destinationUrl": "example.com",
                "protocol": "0",
                "date": "2000-01-20",
                "time": "00:00:00",
                "timeZone": "-00:00",
                "sample": "This is example content threat information.",
                "sampleType": "text/plain"
              }
            }
          ]
        }
      }
    ]
  }
}

Response 202

Submitted Successfully

Response 400

Response 401

Response 415

Unsupported Media Type

Response 500

Internal Server Error

Code samples


Curl

@ECHO OFF

curl -v -X POST "https://api.msrc.microsoft.com/testing/engage/cars?api-version={string}"
-H "Content-Type: application/json"
-H "Api-Key: {subscription key}"
-H "Authorization: {access token}"

--data-ascii "{body}" 

C#

using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;

namespace CSHttpClientSample
{
    static class Program
    {
        static void Main()
        {
            MakeRequest();
            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }
        
        static async void MakeRequest()
        {
            var client = new HttpClient();
            var queryString = HttpUtility.ParseQueryString(string.Empty);

            // Request headers
            client.DefaultRequestHeaders.Add("Api-Key", "{subscription key}");
            client.DefaultRequestHeaders.Add("Authorization", "{access token}");

            // Request parameters
            queryString["api-version"] = "{string}";
            var uri = "https://api.msrc.microsoft.com/testing/engage/cars?" + queryString;

            HttpResponseMessage response;

            // Request body
            byte[] byteData = Encoding.UTF8.GetBytes("{body}");

            using (var content = new ByteArrayContent(byteData))
            {
               content.Headers.ContentType = new MediaTypeHeaderValue("< your content type, i.e. application/json >");
               response = await client.PostAsync(uri, content);
            }

        }
    }
}	

Java

// // This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class JavaSample 
{
    public static void main(String[] args) 
    {
        HttpClient httpclient = HttpClients.createDefault();

        try
        {
            URIBuilder builder = new URIBuilder("https://api.msrc.microsoft.com/testing/engage/cars");

            builder.setParameter("api-version", "{string}");

            URI uri = builder.build();
            HttpPost request = new HttpPost(uri);
            request.setHeader("Content-Type", "application/json");
            request.setHeader("Api-Key", "{subscription key}");
            request.setHeader("Authorization", "{access token}");


            // Request body
            StringEntity reqEntity = new StringEntity("{body}");
            request.setEntity(reqEntity);

            HttpResponse response = httpclient.execute(request);
            HttpEntity entity = response.getEntity();

            if (entity != null) 
            {
                System.out.println(EntityUtils.toString(entity));
            }
        }
        catch (Exception e)
        {
            System.out.println(e.getMessage());
        }
    }
}


JavaScript

<!DOCTYPE html>
<html>
<head>
    <title>JSSample</title>
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>

<script type="text/javascript">
    $(function() {
        var params = {
            // Request parameters
            "api-version": "{string}",
        };
      
        $.ajax({
            url: "https://api.msrc.microsoft.com/testing/engage/cars?" + $.param(params),
            beforeSend: function(xhrObj){
                // Request headers
                xhrObj.setRequestHeader("Content-Type","application/json");
                xhrObj.setRequestHeader("Api-Key","{subscription key}");
                xhrObj.setRequestHeader("Authorization","{access token}");
            },
            type: "POST",
            // Request body
            data: "{body}",
        })
        .done(function(data) {
            alert("success");
        })
        .fail(function() {
            alert("error");
        });
    });
</script>
</body>
</html>

ObjC

#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
    NSString* path = @"https://api.msrc.microsoft.com/testing/engage/cars";
    NSArray* array = @[
                         // Request parameters
                         @"entities=true",
                         @"api-version={string}",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];

    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"POST"];
    // Request headers
    [_request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
    [_request setValue:@"{subscription key}" forHTTPHeaderField:@"Api-Key"];
    [_request setValue:@"{access token}" forHTTPHeaderField:@"Authorization"];
    // Request body
    [_request setHTTPBody:[@"{body}" dataUsingEncoding:NSUTF8StringEncoding]];
    
    NSURLResponse *response = nil;
    NSError *error = nil;
    NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];

    if (nil != error)
    {
        NSLog(@"Error: %@", error);
    }
    else
    {
        NSError* error = nil;
        NSMutableDictionary* json = nil;
        NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
        NSLog(@"%@", dataString);
        
        if (nil != _connectionData)
        {
            json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
        }
        
        if (error || !json)
        {
            NSLog(@"Could not parse loaded json with error:%@", error);
        }
        
        NSLog(@"%@", json);
        _connectionData = nil;
    }
    
    [pool drain];

    return 0;
}

PHP

<?php
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
require_once 'HTTP/Request2.php';

$request = new Http_Request2('https://api.msrc.microsoft.com/testing/engage/cars');
$url = $request->getUrl();

$headers = array(
    // Request headers
    'Content-Type' => 'application/json',
    'Api-Key' => '{subscription key}',
    'Authorization' => '{access token}',
);

$request->setHeader($headers);

$parameters = array(
    // Request parameters
    'api-version' => '{string}',
);

$url->setQueryVariables($parameters);

$request->setMethod(HTTP_Request2::METHOD_POST);

// Request body
$request->setBody("{body}");

try
{
    $response = $request->send();
    echo $response->getBody();
}
catch (HttpException $ex)
{
    echo $ex;
}

?>

Python

########### Python 2.7 #############
import httplib, urllib, base64

headers = {
    # Request headers
    'Content-Type': 'application/json',
    'Api-Key': '{subscription key}',
    'Authorization': '{access token}',
}

params = urllib.urlencode({
    # Request parameters
    'api-version': '{string}',
})

try:
    conn = httplib.HTTPSConnection('api.msrc.microsoft.com')
    conn.request("POST", "/testing/engage/cars?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

headers = {
    # Request headers
    'Content-Type': 'application/json',
    'Api-Key': '{subscription key}',
    'Authorization': '{access token}',
}

params = urllib.parse.urlencode({
    # Request parameters
    'api-version': '{string}',
})

try:
    conn = http.client.HTTPSConnection('api.msrc.microsoft.com')
    conn.request("POST", "/testing/engage/cars?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

Ruby

require 'net/http'

uri = URI('https://api.msrc.microsoft.com/testing/engage/cars')

query = URI.encode_www_form({
    # Request parameters
    'api-version' => '{string}'
})

if uri.query && uri.query.length > 0
    uri.query += '&' + query
else
    uri.query = query
end

request = Net::HTTP::Post.new(uri.request_uri)
# Request headers
request['Content-Type'] = 'application/json'
# Request headers
request['Api-Key'] = '{subscription key}'
# Request headers
request['Authorization'] = '{access token}'
# Request body
request.body = "{body}"

response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
    http.request(request)
end

puts response.body