CSAF Should Support Modern RESTful APIs instead of just ROLIE or Directory Listing

[santosomar]

There are several ways to structure data transmission. CSAF currently suggests the providers to use some traditional methods of distribution the directory listing of JSON files and ROLIE. Most modern security tools use Representational State Transfer (REST) APIs. Unfortunately, ROLIE is not widely adopted in the industry. Though both can serve as platforms for data exchange, they have differences in functionality, flexibility, and scalability, making REST APIs the preferred choice for many developers.

REST APIs operate based on a universal standard and are inherently consistent. They're typically developed around HTTP methods, such as GET, POST, PUT, and DELETE, making them intuitive to use. This simplifies the learning curve for developers and promotes consistency across diverse applications. This is similar in ROLIE.

In contrast, a directory of JSON files lacks these standards. The lack of an established protocol might lead to inconsistencies, making it hard to maintain, particularly for large-scale projects or teams with multiple developers.

REST APIs often include measures to protect data integrity and confidentiality. Features such as authentication, authorization, and encryption ensure that only authorized parties can access and modify the data.

On the other hand, a directory listing of JSON files might not inherently provide these security features. While you can implement security measures, doing so consistently and robustly could be challenging.

A REST API returns precisely the data requested, reducing the load on both the server and client side. Using pagination and other techniques, it allows a large dataset to be efficiently transmitted in smaller chunks. In contrast, directory listing of JSON files could entail downloading whole files, even when only a small portion of the data is required. This inefficiency may lead to increased network traffic and slower performance.

REST APIs are designed with scalability in mind, allowing easy expansion of services and functionalities. They allow for changes in underlying databases or systems without affecting the client-side application, offering a greater level of abstraction. For example, I can just make a query based on a CVE that I am interested to get the status or disposition. With a directory listing of JSON files, modifications or expansions might require changes on the client-side, reducing flexibility and scalability.

REST APIs support real-time data transmission, which is essential in many modern applications. With technologies like WebSockets or Server-Sent Events, REST APIs can push updates to the client, enabling real-time interactivity. Directory listings of JSON files, by their static nature, cannot easily provide real-time data.

REST APIs usually include robust error handling mechanisms. When a request fails, the API can return a specific HTTP status code and message, making it easy to diagnose and fix issues. Directory listing of JSON files lacks such a built-in error handling mechanism. Recognizing and resolving issues might be more challenging and time-consuming.

The following table highlights the pros and cons of directory listing and REST APIs.

	Directory Listing	REST APIs
Pros	Simple to implement. Can be a viable solution for sharing static files or small sets of data.	Offers standardization and consistency. Efficient data transmission, returning only what's requested. Built-in security features like authentication and authorization. Highly scalable and flexible. Supports real-time data transmission. Robust error handling.
Cons	No built-in security features. Inefficient data transmission, requiring whole file downloads. Not scalable and flexible. Does not support real-time data. No built-in error handling mechanism. Inconsistent, especially with large projects or multiple developers.	More complex to implement than directory listing. Requires understanding of HTTP protocol and REST principles. Might be overkill for simple, static data sharing scenarios.

The following a table compares ROLIE and REST APIs.

	ROLIE	REST APIs
Pros	Tailored for some cybersecurity information exchange. Builds upon REST principles, but not complete. Provides standardization for the specific use case of security information sharing.	Flexible and can be used for a wide range of applications. Offers standardization and consistency. Efficient data transmission, returning only what's requested. Built-in security features like authentication and authorization. Highly scalable and flexible. Supports real-time data transmission. Robust error handling.
Cons	Not widely adopted. Most solutions use RESTful APIs. Specific to a particular use case, making it less flexible for other applications. Requires understanding of both REST principles and the specifics of the ROLIE standard.	Requires understanding of HTTP protocol and REST principles. Might be overkill for simple, static data sharing scenarios.

CSAF Must NOT penalize vendors that provide modern RESTful APIs vs ROLIE and Directory Listing. This will hinder the adoption of the standard.

[tschmidtb51]

@santosomar Thank you for bringing this up. I'm happy to work on that specification with you and the TC.

CSAF Must NOT penalize vendors that provide modern RESTful APIs vs ROLIE and Directory Listing.

I totally agree. Nevertheless, we need to specify the API and the required features to make it interoperable.

[tschmidtb51]

A student wrote a RESTful API for CSAF: https://opus.hs-offenburg.de/frontdoor/index/index/start/0/rows/10/sortfield/score/sortorder/desc/searchtype/simple/query/csaf/docId/6011 We need to evaluate whether that fulfills all of our use cases or whether additional routes would need to be established.

[tschmidtb51]

Another student is currently writing his master thesis to challenge the REST-based approach with a GraphQL-based one. Based on that information, we can decide whether REST is the best approach or GraphQL should be used.

[tschmidtb51]

My suggestion to proceed would be:

1. Collect use cases / user stories
2. Look into the two theses to evaluate which use cases are already covert
3. Design the API
4. Create a PoC (I guess that is important also regarding the data storage and matching)
5. Put the API into the standard (or even separate the distribution into an extra specification document)

[santosomar]

I like this suggestion! Thank you @tschmidtb51 ! I will put this in the agenda to discuss at the next TC meeting for initial discussion. We also should also try to collaborate and/or evaluate some of the efforts discussed in https://dbom.io

[sthagen]

This should be the initial collector ticket around API planning.

[tschmidtb51]

The master thesis that looked into GraphQL as a API-base is now published: https://www.fernuni-hagen.de/pv/docs/wiegel-abschlussarbeit.pdf

[tschmidtb51]

Also the Code is online:

• REST API: https://github.com/MexHigh/csaf_distribution
• GraphQL-API: https://github.com/wwiegel/csafApi

[tschmidtb51]

We should also consider the approaches OData and ActivityPub based on the use cases.