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"