pycadf(1)

PYCADF(1)

pycadf

PYCADF(1)

NAME

pycadf - pyCADF Documentation

The CADF (Cloud Audit Data Federation Working Group) is working to develop open standards for audit data which can be federated from cloud providers, with the intent to elevate customer's trust in cloud hosted applications.

Specifications and profiles produced by the CADF will help protect the investments of companies seeking to move their applications to cloud deployment models and preserve their ability to audit operational processes, regardless of their chosen cloud provider. The CADF develops specifications for audit event data and interface models and a compatible interaction model that will describe interactions between IT resources for cloud deployment models.

pyCADF is the python implementation of the CADF specification. This documentation offers information on how CADF works and how to contribute to the project.

GETTING STARTED

Events

The principal goal of this specification is to ensure that similar auditable events, such as a "logon" or "critical resource update" resolve to the same data format with prescriptive data types, entities, and properties to facilitate reporting, query, federation, and aggregation.

Defining Events

The event model is intended to describe the interactions between resources that compose a cloud service. Conceptually, the event is based upon the perspective of a single RESOURCE called the OBSERVER that is responsible for observing the Actual Event and creating the (initial) CADF Event Record.

[image: Figure 1: Observer perspective of an Event] [image]

At a minimum, an Event must include the following attributes to be CADF-compliant: eventType, observer, initiator, target, action, and outcome. CADF's event model is extensible so any additional attributes that may better help describe the event can be added to the event model as an additional attribute.

NOTE:

In some cases, the OBSERVER, INITIATOR, and TARGET could reference the same resource. The precise interpretation of these components, therefore, will depend somewhat on the type of event being recorded, and the specific activity and resources involved.

Use Case Examples

1.: Auditing access to a controlled resource

Scenario: A cloud provider has a software component that manages identity and access control that we will call an "identity management service". This service is required, by the provider's security policy, to log all user activities including "logon" attempts against any servers within the provider's infrastructure.

[image: Figure 2: Conceptually mapping values of an audit event] [image]

Event Attribute	Value	Reason
eventType	activity	OBSERVER is required to report any user security activity
observer.typeURI	service/security/identity	Value from the CADF Resource Taxonomy most closely describes an "Identity Manager Service"
initiator.typeURI	data/security/account/user	Value from the CADF Resource Taxonomy most closely describes a "user"
action	authenticate/logon	Value from the CADF Action Taxonomy most closely describes a user "logon" action.
target.typeURI	service/compute/node	Value from the CADF Resource Taxonomy most closely describes a target "server"
outcome	success	Any valid CADF Outcome Taxonomy value that describes result of action
measurement	N/A	A MEASUREMENT component is not required for "activity" type events.
REASON	N/A	A REASON component is not required for "activity" type events.

Event serialisation (including some optional attributes for additional details):

{


    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",


    "eventTime": "2014-02-27T19:29:30.855665+0000",


    "target": {


        "typeURI": "service/compute/node",


        // optional Endpoints to describe compute node,


        "addresses": [


            {


                "url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6",


                "name": "admin"


            },


            {


                "url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6",


                "name": "private"


            },


            {


                "url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6",


                "name": "public"


            }


        ],


        "id": "06747855d62547d4bfd707f75b8a1c54",


        "name": "nova"


    },


    "observer": {


        "id": "target" // shortform to show Observer Resource is the same as Target,


    },


    // tags use to query events on,


    "tags": [


        "correlation_id?value=56cdde6f-6b4e-48a4-94e6-defb40522fb2"


    ],


    "eventType": "activity",


    "initiator": {


        "typeURI": "data/security/account/user",


        "name": "admin",


        // optional Credential to describe resource,


        "credential": {


            "token": "MIIQzgYJKoZIhvcNAQcCoIIQvzCCELsC xxxxxxxx zqvD9OPWZm7VQpYNK2EvrZi-mTvb5A==",


            "identity_status": "Confirmed"


        },


        // optional Host to describe resource,


        "host": {


            "agent": "python-novaclient",


            "address": "9.26.26.250"


        },


        "project_id": "e7e2bcc9c0df4f3eabcd412ae62503f6",


        "id": "68a3f50705a54f799ce94380fc02ed8a"


    },


    // optional Reason for activity event,


    "reason": {


        "reasonCode": "200",


        "reasonType": "HTTP"


    },


    // list of Resources which edited event,


    "reporterchain": [


        {


            "reporterTime": "2014-02-27T19:29:31.043902+0000",


            "role": "modifier",


            "reporter": {


                "id": "target"


            }


        }


    ],


    "action": "authenticate/logon",


    "outcome": "success",


    "id": "0a196053-95de-48f8-9890-4527b25b5007",


    // Event model is extensible so additional attributes may be added to describe model,


    "requestPath": "/v2/e7e2bcc9c0df4f3eabcd412ae62503f6/os-certificates"
}

2.: Periodic monitoring resource status

Scenario: A cloud provider has software monitoring agents(Ceilometer) installed on every server(Nova) that it makes available as an IaaS resource to its customers. These agents are required to provide periodic informational status of each server's CPU utilisation along with metric data to their operations management software by using the CADF Event Record format.

[image: Figure 3: Conceptually mapping values of an monitor event] [image]

Event Attribute	Value	Reason
eventType	monitor	OBSERVER is required to monitor a server's CPU utilization
observer.typeURI	service/oss/monitoring	Value from the CADF Resource Taxonomy most closely describes a "software monitoring agent"
initiator.typeURI	service/oss/monitoring	OBSERVER is also the INITIATOR of this monitoring event
action	monitor	Value from the CADF Action Taxonomy
target.typeURI	service/compute/cpu	Value from the CADF Resource Taxonomy most closely describes a server’s "cpu"
outcome	success	OBSERVER successfully obtained and reported a CPU utilization measurement
measurement	80%	MEASUREMENT component is required and the observed value is 80% CPU utilisation
reason	N/A	REASON component is not required for "monitor" type events.

Event serialisation:

{


    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",


    "eventTime": "2014-02-27T19:29:30.855665+0000",


    "target": {


        "typeURI": "service/compute/cpu",


        "id": "06747855d62547d4bfd707f75b8a1c54",


        "name": "instance"


    },


    "observer": {


        "id": "initiator"


    },


    "eventType": "monitor",


    "initiator": {


        "typeURI": "service/oss/monitoring",


        "name": "ceilometer-pollster",


        "id": "68a3f50705a54f799ce94380fc02ed8a"


    },


    "measurement": [


        {


            "result": "80",


            "metric": {


                "metricId": "<metric_id>",


                "unit": "%",


                "name": "CPU utilisation metric"


            }


        }


    ],


    "action": "monitor",


    "outcome": "success",


    "id": "0a196053-95de-48f8-9890-4527b25b5007"
}

NOTE:

Additional use cases can be found in the Full CADF specification.

Specification

The following is a high-level description of components in the CADF specification. The basic component of the CADF specification are Events. The full CADF specification document can be found here. Additional details on the CADF specification are accessible via the DMTF CADF page.

Events

The CADF Event Model applies semantics to the activities, resources, information, and changes within a cloud provider's infrastructure and models these using the concept of an event.

Property	Type	Required	Description
id	cadf:Identifier	Yes	The unique identifier of the CADF Event Record
typeURI	cadf:Path	Dependent	Can be used to declare versioning of Events.
eventType	xs:string	Yes	The classification of the type of event
eventTime	cadf:Timestamp	Yes	The OBSERVER's best estimate as to the time the Actual Event occurred or began
action	cadf:Path	Yes	This property represents the event's ACTION
outcome	cadf:Path	Yes	A valid classification value from the CADF Outcome Taxonomy
initiator	cadf:Resource	Dependent	The event's INITIATOR. Required if not initiatorId
initiatorId	cadf:Identifier	Dependent	The event's INITIATOR resource by reference. Required if not initiator
target	cadf:Resource	Dependent	The event's TARGET. Required if not targetId
targetId	cadf:Identifier	Dependent	The event's TARGET by reference. Required if not target
observer	cadf:Resource	Dependent	The event's OBSERVER. Required if not observerId
observerId	cadf:Identifier	Dependent	The event's OBSERVER by reference. Required if not observer
reason	cadf:Reason	No	Domain-specific reason code and policy data that provides an additional level of detail to the outcome value. Required if the eventType property is "control"
severity	xs:string	No	Describes domain-relative severity assigned to the event by the OBSERVER. This property's value is non-normative
measurements	cadf:Measurement[]	Dependent	Any measurement (values) associated with the event. Required if the eventType property is "monitor"
name	xs:string	No	A descriptive name for the event
tags	cadf:Tag[]	No	Array of Tags that MAY be used to further qualify or categorize the CADF Event Record
attachments	cadf:Attachment[]	No	Array of extended or domain-specific information about the event or its context
reporterchain	cadf:Reporterstep[]	No	Array of Reporterstep typed data that contains information about the sequenced handling of or change to the associated CADF Event Record by any REPORTER

Serialisation



   {


    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",


    "id": "a80dc5ee-be83-48ad-ad5e-6577f2217637",


    "eventType": "activity",


    "action": "read",


    "outcome": "success",


    "reason": {


        "reasonCode": "200",


        "reasonType": "HTTP"


    },


    "eventTime": "2014-01-17T23:23:38.109989+0000",


    "initiator": {


        "id": "95f12d248a234a969f456cd2c794f29a",


        "typeURI": "service/security/account/user",


        "name": "admin",


        "project_id": "e55b158759854ea6a7852aa76632c6c1",


        "credential": {


            "token": "MIIQBgYJKoZIhvcNAQcCoIIP9z xxxxxx KoZIhvcIP9z=",


            "identity_status": "Confirmed"


        },


        "host": {


            "agent": "python-novaclient",


            "address": "9.26.27.109"


        }


    },


    "target": {


        "id": "0f126160203748a5b4923f2eb6e3b7db",


        "typeURI": "service/compute/servers",


        "name": "nova",


        "addresses": [


            {


                "url": "http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1",


                "name": "admin"


            },


            {


                "url": "http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1",


                "name": "private"


            },


            {


                "url": "http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1",


                "name": "public"


            }


        ]


    },


    "observer": {


        "id": "target"


    },


    "reporterchain": [


        {


            "reporterTime": "2014-01-17T23:23:38.154152+0000",


            "role": "modifier",


            "reporter": {


                "id": "target"


            }


        }


    ],


    "requestPath": "/v2/56600971-90f3-4370-807f-ab79339381a9/servers",


    "tags": [


        "correlation_id?value=bcac04dc-e0be-4110-862c-347088a7836a"


    ]
}

Attachments

An attachment is a container for data or "content" that may follow any structure - from an atomic type to a complex hierarchy. However, it is desirable for processing and interoperability that the type - or structure - of the content be identified by a simple value. To this end the attachment also contains a "content type", i.e., a URI that identifies the kind of content.

Attachments are intended to be used for inclusion of domain-specific, informative, or descriptive information.

Property	Type	Required	Description
typeURI	xs:anyURI	Yes	The URI that identifies the type of data contained in the "content" property.
content	xs:any	Yes	A container that contains any type of data (as defined by the "contentType" property).
contentType	xs:string	Yes	An optional name that can be used to provide an identifying name for the content.

Serialisation

{


    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",


    ...,


    "attachments": [


        {


            "content": "xs:any",


            "contentType": "xs:anyURI"


        },


        {


            "content": "xs:any",


            "contentType": "xs:anyURI"


        }


    ]
}

Credentials

This type provides a means to describe various credentials along with any information about the authority that is responsible for maintaining them. This is intended to be associated with a CADF Resource's identity and reflects any authorizations or identity assertions the resource may use to gain access to other resources.

Property	Type	Required	Description
type	xs:anyURI	No	Type of credential. (e.g., auth. token, identity token, etc.)
token	xs:any	Yes	The primary opaque or non-opaque identity or security token (e.g., an opaque or obfuscated user ID)
authority	xs:anyURI	No	The trusted authority (a service) that understands and can verify the credential.
assertions	cadf:Map	No	Optional list of additional assertions or attributes that belong to the credential

Serialisation

{


    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",


    "action": "authenticate",


    ...,


    "initiator": {


        "id": "joe.user@example.com",


        "typeURI": "data/security/account/user",


        ...,


        "credential": {


            "type": "https://mycloud.com/v2/token",


            "token": "myuuid:1ef0-abdf-xxxx-xxxx"


        }


    }
}

Endpoints

The Endpoint type is used to provide information about a resource's location on a network.

Property	Type	Required	Description
url	xs:anyURI	Yes	The network address of the endpoint; for IP-based addresses
name	xs:string	No	An optional property to provide a logical name for the endpoint
port	xs:string	No	An optional property to provide the port value separate from the address property

Serialisation



   {


    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",


    ...,


    "target": {


        "id": "myscheme://mydomain/resource/id/0001",


        "name": "server_0001",


        "addresses": [


            {


                "name": "public",


                "url": "http://mydomain/mypath/server-0001/"


            },


            ...


        ],


        ...


    }
}

Geolocations

Geolocation information, which reveals a resource's physical location, is obtained by using tracking technologies such as global positioning system (GPS) devices, or IP geolocation by using databases that map IP addresses to geographic locations. Geolocation information is widely used in context-sensitive content delivery, enforcing location-based access restrictions on services, and fraud detection and prevention.

Due to the intense concerns about security and privacy, countries and regions introduced various legislation and regulation. To determine whether an event is compliant sometimes depends on the geolocation of the event. Therefore, it is crucial to report geolocation information unambiguously in an audit trail.

Property	Type	Required	Description
id	xs:anyURI	No	Optional identifier for a geolocation
latitude	xs:string	No	The latitude of a geolocation
longitude	xs:string	No	The longitude of a geolocation
elevation	xs:double	No	The elevation of a geolocation in meters
accuracy	xs:double	No	The accuracy of a geolocation in meters
city	xs:string	No	The city of a geolocation
state	xs:string	No	The state/province of a geolocation
regionICANN	xs:string	No	A region (e.g., a country, a sovereign state, a dependent territory or a special area of geographical interest)
annotations	cadf:Map	No	User-defined geolocation information (e.g., building name, room number)

Usage Requirements

1.: Geolocation typed data SHALL contain at least one valid property and associated value.
2.: Geolocation typed data SHALL NOT be used to represent virtual or logical locations (e.g. network zone).
3.: For each geolocation data instance, the properties SHALL be consistent. That is, all properties SHALL consistently represent the same geographic location and SHALL NOT provide conflicting value data.

NOTE:

latitude, longitude and region are all supplied as properties describing the same geolocation, the latitude and longitude properties coordinate values should resolve to the same geographic location as described by the value of the region property.

4.: ICANN's implementation plan states "Upper and lower case characters are considered to be syntactically and semantically identical"; therefore, the "regionICANN" property's values MAY be either upper or lower case.

Serialisation

{


    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",


    ...,


    "target": {


        ...,


        "geolocation": {


            "latitude": "+372207.90",


            "longitude": "-1220210.20",


            "elevation": "10"


        }


    }
}

Hosts

Most resources that are referenced in an IT or cloud infrastructure are conceptually "hosted on" or "hosted by" other resources. For example, "applications" are hosted on "web servers" or "users" may be hosted on a "network connected device" or a "terminal". In addition, networked resources are "hosted" by some device attached to some network.

The host resource often provides context or location information for the resource it is hosting at the time the Actual Event was observed and recorded (e.g., an IP address, software agent, platform, etc.). Providing a means to record host information with a CADF Event Record is valuable for audit purposes because compliance policies and rules are often based on such information.

Property	Type	Required	Description
id	cadf:Identifier	No	The optional identifier of the host RESOURCE
address	xs:anyURI	No	The optional address of the host RESOURCE
agent	xs:string	No	The optional agent (name) of the host RESOURCE
platform	xs:string	No	The optional platform of the host RESOURCE

Serialisation

{


    "id": "myuuid:1234-5678-90abc-defg-0000",


    "address": "10.0.2.15",


    "agent": "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:18.0)",


    "platform": "Linux version 3.5.0-23-generic (gcc version 4.6.3 (Ubuntu/Linaro 4.6.3-1ubuntu5) ) #35~precise1-Ubuntu SMP Fri Jan 25 17:15:33 UTC 2013"
}

Identifiers

This specification defines an Identifier type that is based upon the Uniform Resource Identifier Reference (URI) as specified in RFC3986. Any value that represents a CADF Identifier type in this specification, its extensions, or profiles SHALL adhere to the requirements listed in this section:

NOTE:

CADF Identifier type values SHALL be created to be Universally Unique Identifiers (UUIDs) so that when CADF data (e.g., CADF Event Records, Logs, Reports, Resources, Metrics, etc.) are federated it will be uniquely identifiable to the source (e.g., cloud provider, service, etc.) that created them.

Measurements

A component that contains statistical or measurement information for TARGET resources that are being monitored. The measurement should be based upon a defined metric (a method of measurement).

Property	Type	Required	Description
result	xs:any	Yes	The quantitative or qualitative result of a measurement from applying the associated metric
metric	cadf:Metric	Dependent	The property describes the metric used in generating the measurement result. Required if not metricId
metricId	cadf:Identifier	Dependent	This property identifies a CADF Metric by reference and whose definition exists elsewhere. Required if not metric
calculatedBy	cadf:Resource	No	An optional description of the resource that calculated the measurement

Metrics

The Metric data type describes the rules and processes for measuring some activity or resource, resulting in the generation of some values (captured by the Measurement type).

Property	Type	Required	Description
metricId	cadf:identifier	Yes	The identifier for the metric.
unit	xs:string	Yes	The metrics unit (e.g., "ms", "Hz", "GB", etc.)
name	xs:string	No	A descriptive name for metric
annotations	cadf:map	No	User-defined metric information.

Serialisation

{


    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/log",


    ...,


    "metrics": [


        {


            "metricId": "myuuid://metric.org/1234",


            "unit": "GB",


            "name": "Storage Capacity in Gigabytes"


        }


    ],


    ...,


    "events": [


        {


            "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",


            ...,


            "measurements": [


                {


                    "result": "10",


                    "metricId": "myuuid://metric.org/1234"


                }


            ]


        }


    ]
}

Paths

This clause describes how to represent values that are elements of hierarchies. This construct is used for example when providing values from CADF Taxonomies that classify components of the CADF Event Model within CADF Event Records as path values.

Reasons

A component that contains a means to provide additional details and further classify the top-level OUTCOME of the ACTION included in a CADF Event Record.

Property	Type	Required	Description
reasonType	xs:anyURI	No	The domain URI that defines the "reasonCode" property's value
reasonCode	xs:string	No	An optional detailed result code as described by the domain identified in the "reasonType" property
policyType	xs:anyURI	No	The domain URI that defines the "policyId" property’s value
policyId	xs:string	No	An optional identifier that indicates which policy or algorithm was applied in order to achieve the described OUTCOME

Serialisation

{


    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",


    ...,


    "reason": {


        "reasonType": "http://www.iana.org/assignments/http-status-codes/http-status-codes.xml",


        "reasonCode": "408",


        "policyType": "http://schemas.xmlsoap.org/ws/2002/12/policy",


        "policyId": "http://10.0.3.4/firewall-ruleset/rule0012"


    },


    ...
}

Reportersteps

This type represents a step in the REPORTERCHAIN that captures information about any notable REPORTER (in addition to the OBSERVER) that modified or relayed the CADF Event Record and any details regarding any modification it performed on the CADF Event Record it is contained within.

The Reporterstep data type should capture information about the resources that have had a role in modifying, or relaying the CADF Event Record during its lifecycle after having been created by the OBSERVER.

Property	Type	Required	Description
role	xs:string	Yes	The role the REPORTER performed on the CADF Event Record (e.g., an "observer", "modifier" or "relay" role)
reporter	cadf:Resource	Dependent	This property defines the resource that acted as a REPORTER on a CADF Event Record. Required if not reporterId
reporterId	cadf:Identifier	Dependent	This property identifies a resource that acted as a REPORTER on a CADF Event Record by reference. Required if not reporter
reporterTime	cadf:Timestamp	No	The time a REPORTER adds its Reporterstep entry into the REPORTERCHAIN
attachments	cadf:Attachment[]	No	An optional array of additional data containing information about the reporter or any action it performed

Serialisation

{


    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",


    ...,


    "reporterchain": [


        {


            "role": "modifier",


            "reporterTime": "2012-03-22T13:00:00-04:00",


            "reporter": {


                "id": "myscheme://mydomain/resource/monitor/id/0002"


            }


        },


        ...


    ]
}

Resources

Resources in general can be used to describe traditional IT components (e.g., servers, network devices, etc.), software components (e.g., platforms, databases, applications, etc.), operational and business data (e.g., accounts, users, etc.) and roles, which can be assigned to persons, that describe the authority to access capabilities.

Property	Type	Required	Description
id	cadf:Identifier	Yes	The identifier for the resource
typeURI	cadf:Path	Yes	The classification (i.e., type) of the resource using the CADF Resource Taxonomy
name	xs:string	No	The optional local name for the resource (not necessarily unique)
domain	xs:string	No	The optional name of the domain that qualifies the name of the resource
credential	cadf:Credential	No	The optional security credentials associated with the resource’s identity
addresses	cadf:Endpoint[]	No	The optional descriptive addresses (including URLs) of the resource
host	cadf:Host	No	The optional information about the (network) host of the resource
geolocation	cadf:Geolocation	Dependent	This optional property describes the geographic location of the resource using Geolocation data type. Required if not geolocationId
geolocationId	cadf:Identifier	Dependent	This optional property identifies a CADF Geolocation by reference. Required if not geolocation
attachments	cadf:Attachment[]	No	An optional array of extended or domain-specific information about the resource or its context

Serialisation

{


    "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",


    ...,


    "target": {


        "id": "myscheme://mydomain/resource/id/0001",


        "typeURI": "service/compute",


        "name": "server_0001",


        ...,


        "geolocation": {


            "city": "Austin",


            "state": "TX",


            "regionICANN": "US"


        }


    }
}

Timestamps

The following example shows the required Lexical representation of the Timestamp type used in this specification; all Timestamp typed values SHALL be formatted accordingly:

yyyy '-' mm '-' dd 'T' hh ':' mm ':' ss ('.' s+)('+' | '-') hh ':' mm

NOTE:

The UTC offset is always required (not optional) and the use of the character 'Z' (or 'Zulu' time) as an abbreviation for UTC offset +00:00 or -00:00 is NOT permitted.

Taxonomy

The CADF Resource Taxonomy describes resources that are commonly used in cloud and enterprise infrastructures. This list was developed based on surveys of existing cloud architectures, deployments, and implementations. The Resource Taxonomy, however, is fully intended to be extensible by profiles that may define additional resource nodes as child nodes to the ones specified below. When doing so, however, vendors and cloud providers should be aware that this places an additional burden on the consumer to correctly comprehend the new node type. Therefore, vendors and providers of CADF audit data should be careful to provide classification values that extend the existing tree from the most granular node that closely matches the functions of any newly-defined resource types. This approach will provide consumers with a baseline understanding of the function of the new resource type.

Audit middleware

pyCADF's version of the audit middleware has been deprecated as of pyCADF 0.8.0. For continued support, the middleware is now maintained under the Identity (Keystone) umbrella. Related documentation can be found here.

Audit maps

The pyCADF library maintains a set of audit mapping files for OpenStack services. Currently, pyCADF supplies the following audit mapping files:

cinder_api_audit_map.conf
glance_api_audit_map.conf
neutron_api_audit_map.conf
nova_api_audit_map.conf
trove_api_audit_map.conf
heat_api_audit_map.conf
ironic_api_audit_map.conf

These files are hosted under the etc/pycadf directory of pyCADF. For more information on how to use these mapping files, refer to the Audit middleware section of the keystonemiddleware project.

CONTRIBUTING

pyCADF utilizes all of the usual OpenStack processes and requirements for contributions. The code is hosted on OpenStack's Git server. Bug reports and blueprints may be submitted to the pycadf project on Launchpad. Code may be submitted to the openstack/pycadf project using Gerrit.

CODE DOCUMENTATION

pycadf

pycadf package

Subpackages

pycadf.helper package

Submodules

pycadf.helper.api module

pycadf.helper.api.convert_req_action(method, details=None): Maps standard HTTP methods to equivalent CADF action

Parameters

method -- HTTP request method
details -- Extra details to append to action.

Module contents

Submodules

pycadf.attachment module

class pycadf.attachment.Attachment(typeURI=None, content=None, name=None): Bases: CADFAbstractType

content

is_valid(): Validation to ensure Attachment required attributes are set.

name

typeURI

pycadf.cadftaxonomy module

pycadf.cadftaxonomy.is_valid_action(value)

pycadf.cadftaxonomy.is_valid_outcome(value)

pycadf.cadftaxonomy.is_valid_resource(value)

pycadf.cadftype module

class pycadf.cadftype.CADFAbstractType: Bases: object
The abstract base class for all CADF (complex) data types (classes).

as_dict(): Return dict representation of Event.

abstract is_valid(value)

class pycadf.cadftype.ValidatorDescriptor(name, func=None): Bases: object

pycadf.cadftype.is_valid_eventType(value)

pycadf.cadftype.is_valid_reporter_role(value)

pycadf.credential module

class pycadf.credential.Credential(token, type=None): Bases: CADFAbstractType

is_valid(): Validation to ensure Credential required attributes are set.

token

type

class pycadf.credential.FederatedCredential(token, type, identity_provider, user, groups): Bases: Credential

groups

identity_provider

is_valid(): Validation to ensure Credential required attributes are set.

user

pycadf.endpoint module

class pycadf.endpoint.Endpoint(url, name=None, port=None): Bases: CADFAbstractType

is_valid(): Validation to ensure Endpoint required attributes are set.

name

port

url

pycadf.event module

class pycadf.event.Event(eventType='activity', id=None, eventTime=None, action='unknown', outcome='unknown', initiator=None, initiatorId=None, target=None, targetId=None, severity=None, reason=None, observer=None, observerId=None, name=None): Bases: CADFAbstractType

action

add_attachment(attachment_val): Add Attachment to Event

Parameters: attachment_val -- Attachment to add to Event

add_measurement(measure_val): Add a measurement value

Parameters: measure_val -- Measurement data type to be added to Event

add_reporterstep(step): Add a Reporterstep

Parameters: step -- Reporterstep to be added to reporterchain

add_tag(tag_val): Add Tag to Event

Parameters: tag_val -- Tag to add to event

eventTime

eventType

id

initiator

initiatorId

is_valid(): Validation to ensure Event required attributes are set.

name

observer

observerId

outcome

reason

severity

target

targetId

pycadf.eventfactory module

class pycadf.eventfactory.EventFactory: Bases: object
Factory class to create different required attributes for the following CADF event types: 'activity': for tracking any interesting system activities for audit 'monitor': Events that carry Metrics and Measurements and support standards such as NIST 'control': For audit events that are based upon (security) policies and reflect some policy decision.

new_event(eventType='activity', **kwargs): Create new event

Parameters: eventType -- eventType of event. Defaults to 'activity'

pycadf.geolocation module

class pycadf.geolocation.Geolocation(id=None, latitude=None, longitude=None, elevation=None, accuracy=None, city=None, state=None, regionICANN=None): Bases: CADFAbstractType

accuracy

city

elevation

id

is_valid()

latitude

longitude

regionICANN

set_annotations(value)

state

pycadf.host module

class pycadf.host.Host(id=None, address=None, agent=None, platform=None): Bases: CADFAbstractType

address

agent

id

is_valid(): Validation to ensure Host required attributes are set.

platform

pycadf.identifier module

pycadf.identifier.generate_uuid(): Generate a CADF identifier.

pycadf.identifier.is_valid(value): Validation to ensure Identifier is correct.
If the Identifier value is a string type but not a valid UUID string, warn against interoperability issues and return True. This relaxes the requirement of having strict UUID checking.

pycadf.measurement module

class pycadf.measurement.Measurement(result=None, metric=None, metricId=None, calculatedBy=None): Bases: CADFAbstractType

calculatedBy

is_valid(): Validation to ensure Measurement required attributes are set.

metric

metricId

result

pycadf.metric module

class pycadf.metric.Metric(metricId=None, unit=None, name=None): Bases: CADFAbstractType

is_valid(): Validation to ensure Metric required attributes are set.

metricId

name

set_annotations(value)

unit

pycadf.path module

class pycadf.path.Path: Bases: CADFAbstractType

static is_valid(value)

set_path_absolute()

set_path_relative()

pycadf.reason module

class pycadf.reason.Reason(reasonType=None, reasonCode=None, policyType=None, policyId=None): Bases: CADFAbstractType

is_valid(): Validation to ensure Reason required attributes are set.

policyId

policyType

reasonCode

reasonType

pycadf.reporterstep module

class pycadf.reporterstep.Reporterstep(role='modifier', reporterTime=None, reporter=None, reporterId=None): Bases: CADFAbstractType

is_valid(): Validation to ensure Reporterstep required attributes are set.

reporter

reporterId

reporterTime

role

pycadf.resource module

class pycadf.resource.Resource(id=None, typeURI='unknown', name=None, ref=None, domain=None, credential=None, host=None, geolocation=None, geolocationId=None): Bases: CADFAbstractType

add_address(addr): Add CADF endpoints to Resource

Parameters: addr -- CADF Endpoint to add to Resource

add_attachment(attach_val): Add CADF attachment to Resource

Parameters: attach_val -- CADF Attachment to add to Resource

credential

domain

geolocation

geolocationId

host

id

is_valid(): Validation to ensure Resource required attributes are set

name

ref

typeURI

pycadf.tag module

pycadf.tag.generate_name_value_tag(name, value): Generate a CADF tag in the format name?value=<value>

Parameters

name -- name of tag
valuue -- optional value tag

pycadf.tag.is_valid(value): Validation check to ensure proper Tag format

pycadf.timestamp module

pycadf.timestamp.get_utc_now(timezone=None): Return the current UTC time.

Parameters: timezone -- an optional timezone param to offset time to.

pycadf.timestamp.is_valid(value): Validation to ensure timestamp is a string.

pycadf.utils module

pycadf.utils.mask_value(value, s_percent=0.125): Obfuscate a given string to show only a percentage of leading and trailing characters.

Parameters: s_percent -- The percentage (in decimal) of characters to replace

Module contents

RELEASE NOTES

CHANGES

4.0.1

Add missing maps into setup.cfg
Remove audit map for retired ceilometer-api and panko
Remove Python 3.8 support
Remove unused debtcollector

4.0.0

Replace deprecated datetime.utcnow call
Bump hacking
Add Python 3.11 to supported version
Remove usage of six
doc: Drop DJANGO_SETTINGS_MODULE environment
Update setup.cfg classifiers
Fix pep8 gate
remove unicode prefix from code
Add doc/requirements
Update zuul job templates
Drop lower-constraints.txt and its testing
Add Python3 wallaby unit tests

3.1.1

•: Correct a typo in the document

3.1.0

Switch to newer openstackdocstheme version
Fix hacking min version to 3.0.1
Add Python3 victoria unit tests
Update hacking for Python3
Use unittest.mock instead of third party mock

3.0.0

Bump the openstackdocstheme extension to 1.20
Drop python 2.7 support and testing
Change README.rst with a better title
Add swift_api_audit_map.conf to setup.cfg
Switch to Ussuri jobs
Update source link in readme
Update the constraints url
Add swift_api_audit_map.conf

2.10.0

Add Python 3 Train unit tests
Removes temporary fix for doc generation
OpenDev Migration Patch
Add py37 tox env and drop py35
add python 3.7 unit test job

2.9.0

Add release note for MD5 hash removal
Change openstack-dev to openstack-discuss
Enabling FIPS mode by using sha256 instead of md5
Don't quote {posargs} in tox.ini
Use templates for cover and lower-constraints
add lib-forward-testing-python3 test job
add python 3.6 unit test job
switch documentation job to new PTI
import zuul job settings from project-config
Switch to stestr

2.8.0

fix tox python3 overrides
Remove moxstubout usage
add lower-constraints job
Trivial: Update pypi url to new url
Updated from global requirements
Updated from global requirements

2.7.0

Avoid tox_install.sh for constraints support
Updated from global requirements
Updated from global requirements
Stopping using norm_ns
changed 'target_endpoint_type' value
Adding gnocchi_api_audit_map.conf to pycadf
Removed references to events api
Adding panko_api_audit_map.conf to pycadf
Switch from oslosphinx to openstackdocstheme
Turn on warning-is-error for sphinx build
Update URL in docs as per the doc-migration spec

2.6.0

Updated from global requirements
Updated from global requirements
Updated from global requirements
Updated from global requirements
Updated from global requirements
Make `is_valid` more flexible with uuid validation
Use https for *.openstack.org references

2.5.0

Remove references to Python 3.4
cleanup string
Add Constraints support
Show team and repo badges on README
Updated from global requirements
Updated from global requirements
Changed the home-page link
Updated from global requirements
Updated from global requirements
Clean oslo.i18n

2.4.0

Updated from global requirements
Remove discover from test-requirements
Don't include openstack/common in flake8 exclude list
Updated from global requirements
Fix order of arguments in assertEqual
Updated from global requirements
Updated from global requirements
Updated from global requirements
Updated from global requirements

2.3.0

Add missing os-volumes_boot to nova_api_audit_map.conf
Updated from global requirements
Updated from global requirements
Remove unused pngmath Sphinx extension
Updated from global requirements

2.1.0

Updated from global requirements
Add docstring validation
Adding ironic api specific audit map configuration
Updated from global requirements
Updated from global requirements
Enable cadf support for Heat
Fix wrong use of comma
Updated from global requirements
remove suport for py33
Remove invalid character from neutron_api_audit_map.conf
Put py34 first in the env order of tox

2.0.1

•: relax id validation

2.0.0

Updated from global requirements
Remove Python 2.6 classifier
Remove python 2.6 and cleanup tox.ini
make generate_uuid return valid uuid
Updated from global requirements
Add authenticate and evaluate actions
Change ceilometer endpoint name from telemetry to metering
No need for Oslo Incubator Sync
Document and update existing hacking violations
Add shields.io version/downloads links/badges into README.rst
Include changelog/history in docs
Fix event example
Add event name
Event doc indentation issue
Updated from global requirements
Updated from global requirements
Fixed typo error

1.1.0

Adding barbican specific base resources
Updated from global requirements
Updated from global requirements
Updated from global requirements
Updated from global requirements
Updated from global requirements
ensure id is not empty
Updated from global requirements
Add api_audit_map.conf for Ceilometer project

1.0.0

Remove script already nuked from oslo-incubator
Updated from global requirements
Add unit tests to increase coverage of cadftype
Remove run_cross_tests.sh
drop audit middleware
Add trove conf file to setup.cfg
Added a testcase to cover ValueError in tag.py
Add test to cover mask value for utils.mask_value

0.9.0

Uncap library requirements for liberty
Updated from global requirements
update README.rst to include additional links
Remove empty _templates folder
Add a section for audit maps
Fix formatting error for geolocation note
add a new set of release notes
Clean up pycadf's doc landing page
Add api_audit_map.conf for Trove project
Updated from global requirements
Updated from global requirements
Updated from global requirements
Additional doc clean up
cleanup documentation

0.8.0

Add deprecation message to Audit API
Do not depend on endpoint id existing in the service catalog
Fix oslo.messaging link in docs
Use oslo_context
Use oslo namespaces
Updated from global requirements
Add a new CADF type for keystone trusts
add helper module

0.7.1

Add new CADF taxonomy types
Pull out some CADF taxonomy to be constants
Updated from global requirements

0.7.0

upgrade hacking to 0.10.0
Updated from global requirements
Updated from global requirements
Updated from global requirements
deprecate audit middleware
sync oslo
Updated from global requirements
Workflow documentation is now in infra-manual
Updated from global requirements
Updated from global requirements
Add classifiers for Python 3
Updated from global requirements
Add release notes
Updated from global requirements
Use correct name of oslo debugger script
Remove unused dependencies from pycadf
Use oslo tests fixture
Use oslo.serialization
Sync oslo libraries
Updated from global requirements
Remove dependencies from docs test env in tox.ini
Stop using intersphinx
Updated from global requirements
Updated from global requirements
Use oslo_debug_helper and remove our own version
Updated from global requirements
Updated from global requirements
Work toward Python 3.4 support and testing
Updated from global requirements

0.6.0

add federated credential
define the project goal
Enable PEP8 checks E128, E251 and E265
clean up license headers
add CONTRIBUTING doc
revise readme with a project description
Updated from global requirements
Debug env for tox
Fix a grammatical error in contributing doc
Fix typo comments
Enabled hacking checks H305 and H307
Bump hacking to version 0.9.2
Remove docutils pin
Updated from global requirements
Bump hacking to 0.9.x series
add audit_maps for more OpenStack components
Updated from global requirements

0.5.1

sync oslo
remove token from notifier middleware
Updated from global requirements
reorder documentation
import run_cross_tests.sh from incubator

0.5

Updated from global requirements
add OpenStack Foundation as author
pycadf documentation
Updated from global requirements
add docstrings to functions

0.4.1

•: catch empty json body

0.4

add constant for security service
audit middleware in pycadf
oslo common code sync and requirements cleanup
Rollback change to that Install configs into /etc
Update .gitreview after repo rename
Install configs into /etc, not /usr/etc

0.3.1

update audit_map
update build_typeURI to drop query string
sync common code and requirements
add path to event
mask token values
adjust typeURI to capture target better
Python 3: update setup.cfg to advertise python 3 compatibility

0.3

Python3: do not index a dict_keys object
Python3: use six.moves.urllib.parse instead of urlparse
Python 3: the request body should be bytes in test_api.py
Python 3: use six.with_metaclass
Python 3: replace 'basestring' by 'six.string_types'
Python 3: Use six.moves.configparser rather than ConfigParser
sync requirements and oslo

0.2.2

add namespace to all ids
improve model validation
update requirements
update oslo
Updated from global requirements
do not set typeURI in resource shortform

0.2.1

switch list action to read/list
support namespace prefix in id
observer and reporter should be valid Resource

0.2

fix conf file settings
Switch to oslo.config 1.2.0 final

0.1.9

•: pycadf 0.1.8 broke oslo

0.1.8

update tox to 1.6
DNS names may not map to service catalog values

0.1.7

•: ensure unique id and timestamp defaults

0.1.6

•: bump oslo.config req to 1.2.0a3

0.1.5

update cadf spec to support new data model
update to use global requirements
Package api_audit_map.conf

0.1.4

•: add event to CADF_EVENT

0.1.3

add support for no response and failed request audit
move cadf correlation id under req.environ

0.1.2

•: append cadf event to req.environ

0.1.1

•: validate attributes against basestring

v0.1

add support for audit api middleware
DMTF CADF format
test commit
initial project setup
Added .gitreview

INDICES AND TABLES

Index
Module Index
Search Page

AUTHOR

OpenStack Foundation

COPYRIGHT

2025, OpenStack Foundation

January 31, 2025

4.0.1

pycadf(1)

NAME

GETTING STARTED

Events

Defining Events

Use Case Examples

Specification

Events

Serialisation

Attachments

Serialisation

Credentials

Serialisation

Endpoints

Serialisation

Geolocations

Usage Requirements

Serialisation

Hosts

Serialisation

Identifiers

Measurements

Metrics

Serialisation

Paths

Reasons

Serialisation

Reportersteps

Serialisation

Resources

Serialisation

Tags

Timestamps

Taxonomy

Audit middleware

Audit maps

CONTRIBUTING

CODE DOCUMENTATION

pycadf

pycadf package

Subpackages

pycadf.helper package

Submodules

pycadf.helper.api module

Module contents

Submodules

pycadf.attachment module

pycadf.cadftaxonomy module

pycadf.cadftype module

pycadf.credential module

pycadf.endpoint module

pycadf.event module

pycadf.eventfactory module

pycadf.geolocation module

pycadf.host module

pycadf.identifier module

pycadf.measurement module

pycadf.metric module

pycadf.path module

pycadf.reason module

pycadf.reporterstep module

pycadf.resource module

pycadf.tag module

pycadf.timestamp module

pycadf.utils module

Module contents

RELEASE NOTES

CHANGES

4.0.1

4.0.0

3.1.1

3.1.0

3.0.0

2.10.0

2.9.0

2.8.0

2.7.0

2.6.0

2.5.0

2.4.0