Skip to content

secure_with_audit

This example demonstrates how to use Python audit hooks to block access to files and URLs.

It installs a audit hook with sys.addaudithook that blocks access to files and URLs that end with blocked.jsonld.

The code in the example then verifies that the audit hook is blocking access to URLs and files as expected.

Functions:

  • audit_hook –

    An audit hook that blocks access when an attempt is made to open a

  • main –

    The main code of the example.

audit_hook 

audit_hook(name: str, args: Tuple[Any, ...]) -> None

An audit hook that blocks access when an attempt is made to open a file or URL that ends with blocked.jsonld.

Details of the audit events can be seen in the audit events table.

Parameters:

  • name

    (str) –

    The name of the audit event.

  • args

    (Tuple[Any, ...]) –

    The arguments of the audit event.

Returns:

  • None –

    None if the audit hook does not block access.

Raises:

  • PermissionError –

    If the file or URL being accessed ends with blocked.jsonld.

Source code in examples/secure_with_audit.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
def audit_hook(name: str, args: Tuple[Any, ...]) -> None:
    """
    An audit hook that blocks access when an attempt is made to open a
    file or URL that ends with `blocked.jsonld`.

    Details of the audit events can be seen in the
    [audit events table](https://docs.python.org/3/library/audit_events.html).

    Args:
        name: The name of the audit event.
        args: The arguments of the audit event.

    Returns:
        `None` if the audit hook does not block access.

    Raises:
        PermissionError: If the file or URL being accessed ends with `blocked.jsonld`.
    """
    if name == "urllib.Request" and args[0].endswith("blocked.jsonld"):
        raise PermissionError("Permission denied for URL")
    if name == "open" and args[0].endswith("blocked.jsonld"):
        raise PermissionError("Permission denied for file")
    return None

main 

main() -> None

The main code of the example.

The important steps are:

  • Install a custom audit hook that blocks some URLs and files.
  • Attempt to parse a JSON-LD document that will result in a blocked URL being accessed.
  • Verify that the audit hook blocked access to the URL.
  • Attempt to parse a JSON-LD document that will result in a blocked file being accessed.
  • Verify that the audit hook blocked access to the file.
Source code in examples/secure_with_audit.py 
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
def main() -> None:
    """
    The main code of the example.

    The important steps are:

    * Install a custom audit hook that blocks some URLs and files.
    * Attempt to parse a JSON-LD document that will result in a blocked URL being accessed.
    * Verify that the audit hook blocked access to the URL.
    * Attempt to parse a JSON-LD document that will result in a blocked file being accessed.
    * Verify that the audit hook blocked access to the file.
    """

    logging.basicConfig(
        level=os.environ.get("PYTHON_LOGGING_LEVEL", logging.INFO),
        stream=sys.stderr,
        datefmt="%Y-%m-%dT%H:%M:%S",
        format=(
            "%(asctime)s.%(msecs)03d %(process)d %(thread)d %(levelno)03d:%(levelname)-8s "
            "%(name)-12s %(module)s:%(lineno)s:%(funcName)s %(message)s"
        ),
    )

    # Install the audit hook
    sys.addaudithook(audit_hook)

    graph = Graph()

    # Attempt to parse a JSON-LD document that will result in the blocked URL
    # being accessed.
    error: Optional[PermissionError] = None
    try:
        graph.parse(
            data=r"""{
            "@context": "http://example.org/blocked.jsonld",
            "@id": "example:subject",
            "example:predicate": { "@id": "example:object" }
        }""",
            format="json-ld",
        )
    except PermissionError as caught:
        logging.info("Permission denied: %s", caught)
        error = caught

    # `Graph.parse` would have resulted in a `PermissionError` being raised from
    # the audit hook.
    assert isinstance(error, PermissionError)
    assert error.args[0] == "Permission denied for URL"

    # Attempt to parse a JSON-LD document that will result in the blocked file
    # being accessed.
    error = None
    try:
        graph.parse(
            data=r"""{
            "@context": "file:///srv/blocked.jsonld",
            "@id": "example:subject",
            "example:predicate": { "@id": "example:object" }
        }""",
            format="json-ld",
        )
    except PermissionError as caught:
        logging.info("Permission denied: %s", caught)
        error = caught

    # `Graph.parse` would have resulted in a `PermissionError` being raised from
    # the audit hook.
    assert isinstance(error, PermissionError)
    assert error.args[0] == "Permission denied for file"