Documenting the A6 REST API

So after a week off (filled with good things like finishing Season 4 of Galactica), I decided I needed to actually document the A6 API. I'm doing this for two reasons:

1. The blog posts are fragmented and make it harder for any potential implementers to follow
2. I like detailed documentation

So here's section 1.0 of draft 0.1 - the three salient elements are the introduction, the license and design philosophy.

A6 API Documentation - Draft 0.1

Can we do the Security Stack API RESTfully? (Part 5)

In part 4 of security stack API series, the /ssapi/element/xccdf/ URI was described, which allows elements in the environment to express their security status via XCCDF (eXtensible Configuration Checklist Description Format). Now that we have a private part of the stack for data collection, we're going to jump back to the public stack to expose an anonymized aspect of the data.

• /ssapi/environment/registered/ - a GET request will return the total number of elements registered with the aggregator, specifically, how many have uploaded a registration payload.
• /ssapi/environment/validated/ - a GET request will return the total number of registered elements that have uploaded.
• /ssapi/environment/freshness/new/ - a GET request will return how many seconds have passed since any element updated their current XCCDF test result.
• /ssapi/environment/freshness/old/ - a GET request will return the age, in seconds, of the oldest current XCCDF test result for any element.
• /ssapi/environment/freshness/mean/ - a GET request will return the mean age, in seconds, for all elements current XCCDF test result.
• /ssapi/environment/freshness/median/ - a GET request will return the median age, in seconds, for all elements current XCCDF test result.
• /ssapi/environment/freshness/@all - a GET request will return an XML blob containing a list of h(UUID4's) (the arbitrary handle that only the aggregator can connect back to a specific element - SHA-2 hashed along with a secret value to reduce likelihood of correlation) along with the age in seconds of the current XCCDF test result.
• /ssapi/environment/score/current/@all - a GET request will return an XML blob containing a list of h(UUID4's) - described immediately above - along with the current XCCDF score value for each element.
• /ssapi/environment/score/trend/@all - a GET request will return an XML blob containing a list of h(UUID4's) - described immediately above - along with a keyword attribute indicating if the score had "improved", "degraded" or "new". The new keyword is used in cases where a new XCCDF test package has been used (may mean the reporting element itself is new or the package has just changed).
• /ssapi/environment/score/count/@all - a GET request will return an XML blob containing a list of h(UUID4's) - described two URI's above - along with a the total count of XCCDF test results uploaded.

Notes:

• While all of the above URI's are public, none of them expose detailed information about the environment that will tell an attacker what defences they're up against or the specific state that any element is in.
• The /ssapi/environment/ URI's provide anonymized data about the environment, that assuming the stack isn't lying about, tell the requester how broad the providers security efforts are, how much coverage they provide and how frequently they're examining or improving their environment and the elements therein. Ultimately though, it's up to the consuming organization to determine if the providers security efforts, as expressed through the stack, are sufficient.
• Administrators with authenticated access to the private part of the stack, specifically the URI /ssapi/element/xccdf/results/ (described in part 4), can view the actual results.

@mhanco suggested we need to address message level security, I completely agree, but want to defer detailed XML payload structures (or other formats) until we've got the broader structure mapped out.

more to come...

Can we do the Security Stack API RESTfully? (Part 4)

(Mrs Iron Fog is awesome - she does my chores for me so I can blog)

(Part 3 is here)

Using the previously described /ssapi/register/ an element can push up information about their security state. This data is considered private and wouldn't be exposed via the public part of the stack - aggregated or sanitized versions of it might be, but not in its as is form, some of the data could result in damaging information leakage.

In this section we start using another SCAP element, The eXtensible Configuration Checklist Description Format (XCCDF)

• /ssapi/element/xccdf/results/?<uuid4> - an element can POST the results of a configuration check with an XML XCCDF result blob.
• /ssapi/element/xccdf/results/ - an administrative entity can GET a list of elements that have provided test results.
• /ssapi/element/xccdf/results/@all - an administrative entity can GET a list of all available test results for all elements (with URI, date and test type).
• /ssapi/element/xccdf/results/?<uuid4> - an administrative entity can GET the list of recent XCCDF test results, an XML blob is returned with enumerated URI, date and test type.
• /ssapi/element/xccdf/results/current/?<uuid4> - an administrative entity can GET the most recent results from a configuration check. If the original element attempts a GET, an error message is returned (prevents information leakage).
• /ssapi/element/xccdf/results/00000001/?<uuid4> - an administrative entity can GET a specific prior result from a configuration check - exact URI will be provided by the /ssapi/element/xccdf/results/?<uuid4> query.
• /ssapi/element/xccdf/results/current/score/?<uuid4> - an administrative entity can GET the XCCDF standard score from the most recent configuration check.
• /ssapi/element/xccdf/results/00000001/score/?<uuid4> - an administrative entity can GET the XCCDF standard score from a specific prior configuration check

Some additional thoughts:

• elements should be able to upload security information, but not read it. This prevents a malicious entity on the element interrogating the stack aggregator for useful information.
• Within the private part of the stack, there should be URI's that are access restricted to all but high privilege users.
• Again, none of the above is published to the outside world

Next, how to express this information to the public stack without giving the game away...

(minor typo fixed - July 31, 2009)

(fixed incorrect escaping on non-HTML tags)

Can we do the Security Stack API RESTfully? (Part 3)

(Part 1 and Part 2 are here respectively)

(a bit of a shorter post tonight as I was on nephew duty)

So far, I've been focusing on organization elements of the stack, by that I mean things about the provider, specifically policies and compliance.

We're going to start moving into the stack space that deals with individual elements, and where we start using bits of SCAP. Before we can start considering individual elements, we need a way to register an element:

• /ssapi/registration/ - invoked by a POST on an XML payload containing Common Platform Enumeration data, IP address and other unique network identifiers (for example a FQDN - thinking MAC addresses are a problem given network segmentation) returns a UUID and new credentials to be cached by the POSTer. The POSTing element was provided with a limited use credential for the initial registration (consider this an authentication boorstrap). If another element tries to register the same IP address or other unique identifier - note, after having examined CPE, I think my comment earlier this morning about self-asserted URI's into a namespace ("I am 10.45.0.34" & "I am http://www.f5.com/products/...") was slightly off, so I'm changing course a little.
• /ssapi/registration/ - invoked by an authenticated DELETE will unregister the element. Invoked by an authenticated PUT will allow the element to update previously provided data including the network identifier, if and only if that identifier hasn't been claimed by anyone else (if it has, an error message is returned).

The registration payload could look like this:

<registration>

<networkID>

<IP address="10.45.0.24" />

<FQDN name="grump1234.xyz.corp" />

</networkID>

<cpe name="cpe:/o:sun:solaris:5.10" />

</registration>

note: I'm being lazy, this is not fully formed XML, pseudo XML at best

A few more thoughts:

• this is a RESTful API, which implies web servers, but I don't think we want to start running embedded web servers all over the place (not a fan of increasing attack surfaces). So most elements in an environment would push information to a purpose built aggregator.
• Much of the data that could be returned by the stack is not for public (or valued customer) consumption. That means part of this stack will be a generalized security information collection and sharing mechanism - I want to avoid repeating the wheel. The other part, and I think this is the most important thing we can accomplish, the stack provides cloud users with a tool and shared meaning to be confident in their cloud providers security.
• I haven't said anything about authenticating access to the stack or access restrictions to parts of the stack - I'm thinking OAuth for the former and something akin to SNMP's public/private for the access restrictions (keep it simple for now, refine in v2.x).
• The unique network identifier used by the element should be strongly bound to the element, that is we need some way to prevent impersonation of one element by a malicious element - client side x509 certs are the easy answer but impose deployment overhead, will need to think more on this. Once registration is complete, the unique network identifier must be bound to the issued credentials and UUID.
• I've avoided discovery for now, you could use a trusted feed from NMAP to populate some of your data set, but you still need to register the element for future conversation, although I suppose one feature implementation could be an agentless aggregator that also provides element security state using remote scanning.

Thanks to @lmacvittie for some thoughts on unique identifiers which led to a discussion on auto-discovery and other goodness - the bad news is that the security stack has a lot more work to be put in, so maybe the squirrel won't get his Friday wish, the goods news is Monday is a public holiday, so lots of thinking time this long weekend.

more to follow...

note: made some minor changes post a reread - removed incorrect reference to shared secret and revised URI to include UUID.