For many years the primary delivery mechanism of our free daily network reports has been email, with messages containing either attachments with the specific report content or download links to the data files themselves. This has not always been a reliable mechanism due to various types of mail delivery failures – including filling of mailboxes, mail configuration errors or blocklisting, and even recipients on the lists accidentally unsubscribing or departing the organization without passing on the subscription information.
To help make report delivery more effective we then introduced an authenticated, per-recipient download website, where each report recipient could download the daily report files via HTTPS. This was a more reliable and secure delivery method, but lacked flexibility and was severely limited due to architecture implementation and trying to keep it integrated with Mailman, our mailing list technology of choice.
We are now happy to announce a completely new way of accessing our reports – via a RESTful API.
Every report recipient can now choose to opt in to this delivery method and receive a unique API key and secret. The Reports API requires that the client send their API key as well as a hash based message authentication code (HMAC) of the request data created with a secret given to each client. Recalculating and comparing the hash allows the server to authenticate the user and to ensure that the request has not been tampered with.
This will also allow us to more easily assign the API key to an organization instead of an individual, allowing for a better transition through the change over of personnel. It will also facilitate automation of the data, reports, and even limited queries of the report data from the API.
An introduction to the new Reports API can be found in API:Documentation. It describes the API endpoints along with example code in Perl and Python that can help with API interaction, testing and help modules usage.
The full Reports API is described in detail in API: Reports Query. The API is meant to query different reports received as well as to do basic queries of the data itself. Queries allow for the following actions (see API: Reports Query for more details):
- List of reports types available for download
- List of actual reports that could be downloaded
- Download specific report
- Query the stored data
Note that the reports themselves are still in the form of CSV files with each report type being in their own distinct format, as described here.
As always, the queries and the data that is delivered is only from the reports that a recipient would have normally received. Every recipient only gets data for the networks they are responsible for (or in the case of a National CERT/CSIRT, the country they are responsible for). Recipients will not be able to request or receive data about other networks or systems that are not theirs.
If you are already an existing subscriber you will continue receiving reports using the e-mail/download link methods. However, if you would like to change the way you access our reports to the new API: Reports Query method, please make a request via our contact form page (you need to nominate an email address that you wish to associate with API use). You also have the option to continue to receive reports by email as well as accessing them with the API.
We hope that the new Reports API will simplify access to our daily free reports. For any feedback, questions and comments, please contact us.