manpages

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"


        }


    }
}


Tags

A "tag" is a label that can be added to a CADF Event Record to qualify or categorize an event.

Tags provide a powerful mechanism for adding domain-specific identifiers and classifications to CADF Event Records that can be referenced by the CADF Query Interface. This allows customers to construct custom reports or views on the event data held by a provider for a specific domain of interest. A CADF Event Record can have multiple tags that enable cross-domain analysis.

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

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
  • Expand © and remove unnecessary encoding lines
  • 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

2023, OpenStack Foundation

February 19, 2023 3.1.1