PyCADF Library

4.0.1 · active · verified Thu Apr 16

The pycadf library provides an auditing data model based on the Cloud Auditing Data Federation (CADF) specification. It is primarily used within the OpenStack ecosystem to establish strict expectations for auditors regarding audit notifications and event structures. The library is actively maintained by the OpenStack project and is currently at version 4.0.1.

Common errors

```
TypeError: __init__() missing 1 required positional argument: 'typeURI'
```
cause When creating a CADF Resource or Event, essential fields like 'typeURI' (for Resource) or 'eventType', 'outcome', 'action' (for Event) are mandatory and must be provided during instantiation.

fix Always provide all required arguments to the `Event` and `Resource` constructors. Consult the CADF specification or pycadf documentation for mandatory fields. For `Resource`, `typeURI` and `id` are crucial. For `Event`, `eventType`, `outcome`, `action`, `initiator`, `target`, `eventTime`, and `id` are common mandatory fields.
```
ImportError: cannot import name 'Event' from 'pycadf.events'
```
cause This error typically means the 'pycadf' package is either not installed, or there's a typo in the import path. The common root package for pycadf's modules is `pycadf`.

fix Ensure `pycadf` is installed via `pip install pycadf`. Double-check the import statement for typos: `from pycadf.events import Event` and `from pycadf.resource import Resource` are the correct paths for core objects.
```
ValueError: Invalid outcome 'fail'
```
cause CADF events have a strict taxonomy for fields like 'outcome' and 'action'. Using values not defined in the CADF specification will lead to validation errors.

fix Refer to the CADF specification or the `pycadf.cadftaxonomy` module (e.g., `pycadf.cadftaxonomy.OUTCOME_TAXONOMY`) for valid values for 'outcome' ('success', 'failure', 'pending', 'unknown') and 'action'.

Warnings

breaking PyCADF version 4.0.0 and later no longer support Python 3.8. Users on Python 3.8 will encounter installation or runtime errors.
Fix: Upgrade your Python environment to version 3.9 or higher. The officially supported minimum is Python 3.9.
gotcha As an OpenStack project, pycadf relies on common OpenStack libraries (oslo.config, oslo.serialization). While these are installed as dependencies, be aware of their presence if integrating pycadf into non-OpenStack environments.
Fix: Ensure that if you have specific versioning requirements for 'oslo' libraries in your project, they are compatible with the versions required by pycadf.

Install

pip install pycadf Install PyPI package

Imports

Event
```
from pycadf.events import Event
```
Resource
```
from pycadf.resource import Resource
```

CADF_VERSION_1_0_0

from pycadf.cadftype import CADF_VERSION_1_0_0

Quickstart

This quickstart demonstrates how to create a basic CADF audit event by defining an initiator (user), a target (VM instance), and then constructing an Event object. The event is then serialized to a JSON string for auditing purposes.

import json
from pycadf.events import Event
from pycadf.resource import Resource
from pycadf.cadftype import CADF_VERSION_1_0_0

# Define initiator resource
initiator = Resource(
    typeURI=CADF_VERSION_1_0_0 + 'security/account/user',
    id='example-user-id',
    name='example_auditor',
    domainId='example-domain'
)

# Define target resource
target = Resource(
    typeURI=CADF_VERSION_1_0_0 + 'compute/instance',
    id='example-instance-id',
    name='my_vm',
    host=Resource(
        typeURI=CADF_VERSION_1_0_0 + 'compute/host',
        id='example-host-id',
        name='compute-host-1'
    )
)

# Create a CADF event
event = Event(
    eventType='activity',
    outcome='success',
    action='create',
    initiator=initiator,
    target=target,
    eventTime='2026-04-16T15:00:00.000Z', # ISO 8601 format
    id='example-event-id'
)

# Serialize the event to a dictionary and print as JSON
print(json.dumps(event.as_dict(), indent=2))

view raw JSON →