Access Check

The access_check module provides the interface for implementing access checks to configuration documents.

There is also a default implementation provided you find in the file_access_check module. This implementation is used by default, but you can customize it by creating a own instance and passing it to the parser.

Usage

Use the Default Implementation with Flags

You can customize access to configuration files by creating a own instance of FileAccessCheck and passing it to the parser.

from erbsland.conf import AccessFeature, FileAccessCheck, Parser

flags = (
        AccessFeature.SAME_DIRECTORY |
        AccessFeature.SUBDIRECTORIES |
        AccessFeature.LIMIT_SIZE |
        AccessFeature.REQUIRE_SUFFIX
)
access_check = FileAccessCheck(flags)
parser = Parser()
parser.access_check = access_check
parser.parse("configuration.elcl")

Create your Custom Access Check

If you need custom logic to check access to configuration files, you can create your own implementation of AccessCheck. Only the method check() needs to be implemented.

Return GRANTED if access is granted, DENIED otherwise. Alternatively you can raise an ConfAccessError if access is denied. If you raise an exception, the parser will automatically add the location of the include statement to the error message.

from erbsland.conf import AccessCheck, AccessCheckResult, AccessSources

class MyAccessCheck(AccessCheck):
    def check(self, access_sources: AccessSources) -> AccessCheckResult:
        # ...
        return AccessCheckResult.GRANTED

Interface

class AccessSources(source: SourceIdentifier, parent: SourceIdentifier | None, root: SourceIdentifier)

Identifiers for the target source and its lineage.

Variables:

source – Identifier of the source being checked.
parent – Identifier of the parent source, or None if the source has no parent.
root – Identifier of the root source.

class AccessCheckResult(*values)

Result of an access check.

GRANTED = 1: Tested source may be accessed.

DENIED = 2: Tested source may not be accessed.

class AccessCheck

Interface for checking whether a source may be accessed.

abstractmethod check(access_sources: AccessSources) → AccessCheckResult

Evaluate access for the given sources.

In case of an error, the check can return DENIED or simply raise a ConfAccessError exception, which is equivalent to AccessCheckResult.DENIED.

Parameters:: access_sources – Identifiers of the source to evaluate.
Returns:: The result of the access check.
Raises:: Error – If the check fails due to an unexpected problem.

class AccessFeature(*values)

Feature flags controlling file access restrictions.

The default configuration enables SAME_DIRECTORY, SUBDIRECTORIES, and LIMIT_SIZE.

If none of SAME_DIRECTORY, SUBDIRECTORIES or ANY_DIRECTORY is set, all file sources are rejected.
If a file is included from a non-file source and ANY_DIRECTORY is not enabled, the source is rejected.

SAME_DIRECTORY = 1: Allow included sources to be in the same directory as the including document (recommended, default). Example: If the including document has the path config/main.elcl, documents such as config/other.elcl are accepted. If disabled, such documents are rejected.

SUBDIRECTORIES = 2: Allow included sources in subdirectories of the including document (recommended, default). Example: If the including document is config/main.elcl, documents like config/sub/other.elcl are accepted. If disabled, subdirectory documents are rejected.

ANY_DIRECTORY = 4: Allow included sources in any directory, including unrelated paths or remote shares. Not recommended.

ONLY_FILE_SOURCES = 8: When enabled, only file-based sources are accepted. Sources of other types (for example, text) are rejected. When disabled (default), non-file sources are automatically accepted, which allows chaining other checks.

LIMIT_SIZE = 16: Limit file size to a maximum of 100 MB (recommended, default).

REQUIRE_SUFFIX = 32: Only allow file sources with an .elcl suffix.

DEFAULTS = 19: Default set of enabled features.

class FileAccessCheck(features: AccessFeature = DEFAULTS)

Access check implementation for file-based sources.

check(access_sources: AccessSources) → AccessCheckResult

Validate access to a file source.

Parameters:

access_sources – Information about the source that is accessed.

Returns:

GRANTED if access is allowed, otherwise DENIED.

Raises:

ConfAccessError – If access is denied due to a restriction.
Error – If resolving a path fails.