pain001.security package#

Security utilities for Pain001.

Submodules#

pain001.security.dsig module#

W3C XML Digital Signature (XML-DSig) for ISO 20022 financial messages.

exception pain001.security.dsig.XmlSignatureError[source]#

Bases: Exception

Raised when XML digital signature generation or verification fails.

pain001.security.dsig.canonicalize_xml(xml_content: str | Element) → str[source]#

Produce W3C Exclusive Canonicalized XML (c14n) string.

Parameters:

xml_content – An XML string or ElementTree.Element.

Returns:

The canonicalized XML string.

pain001.security.dsig.compute_sha256_digest(canonical_xml: str) → str[source]#

Compute base64-encoded SHA-256 digest of canonical XML.

Parameters:

canonical_xml – The canonical XML string.

Returns:

The base64-encoded digest string.

pain001.security.dsig.sign_xml_document(xml_content: str, private_key_pem: str | bytes, cert_pem: str | bytes | None = None, passphrase: str | bytes | None = None) → str[source]#

Sign an XML document using W3C XML-DSig Enveloped RSA-SHA256 signature.

Parameters:

  • xml_content – The raw XML document string.

  • private_key_pem – RSA private key in PEM format (string or bytes).

  • cert_pem – Optional X.509 certificate in PEM format to embed in KeyInfo.

  • passphrase – Optional passphrase for the private key.

Returns:

The signed XML document string.

Raises:

XmlSignatureError – If key loading or signing fails.

pain001.security.dsig.verify_xml_signature(signed_xml: str | bytes, public_key_pem: str | bytes | None = None, cert_pem: str | bytes | None = None) → bool[source]#

Verify a W3C XML-DSig Enveloped RSA-SHA256 digital signature.

Parameters:

  • signed_xml – The signed XML document string or bytes.

  • public_key_pem – Optional public key in PEM format.

  • cert_pem – Optional X.509 certificate in PEM format.

Returns:

True if signature is valid.

Raises:

XmlSignatureError – If signature verification fails or signature is missing.

pain001.security.formula module#

Formula injection mitigation for CSV and spreadsheet inputs.

pain001.security.formula.FORMULA_PREFIXES: tuple[str, ...] = ('=', '+', '-', '@', '\t', '\r', '\n')#

Characters that spreadsheet engines interpret as formula prefixes.

pain001.security.formula.sanitize_formula_injection(value: str) → str[source]#

Neutralize formula injection by prefixing dangerous characters with a single quote.

When spreadsheet applications (such as Microsoft Excel, LibreOffice Calc, or Google Sheets) open CSV or spreadsheet files, cells starting with formula characters (‘=’, ‘+’, ‘-’, ‘@’, ‘t’, ‘r’, ‘n’) can trigger automatic formula evaluation or command execution (CWE-1236).

Prefixing the value with a single quote (’) forces spreadsheet engines to treat the cell content as literal text rather than an executable formula.

Parameters:

value – The string cell value to sanitize.

Returns:

The sanitized string. If the string starts with any dangerous prefix, it is prefixed with a single quote (‘). Otherwise, the string is returned unchanged.

Examples

>>> sanitize_formula_injection("=cmd|' /C calc'!A0")
"'=cmd|' /C calc'!A0"
>>> sanitize_formula_injection("DE07512108001245126162")
'DE07512108001245126162'

pain001.security.path_validator module#

Path validation and sanitization to prevent security vulnerabilities.

exception pain001.security.path_validator.PathValidationError[source]#

Bases: ValueError

Raised when path validation fails.

exception pain001.security.path_validator.SecurityError[source]#

Bases: PermissionError

Raised when a security boundary is violated.

pain001.security.path_validator.sanitize_for_log(user_input: str, max_length: int = 100) → str[source]#

Sanitize user input for safe logging (prevent log injection).

Parameters:

  • user_input – User-provided string (potentially malicious).

  • max_length – Maximum length to include in log.

Returns:

Sanitized string safe for logging.

pain001.security.path_validator.validate_path(untrusted_path: str | Path, must_exist: bool = False, base_dir: str | Path | None = None) → str[source]#

Validate and resolve path to prevent directory traversal attacks.

Parameters:

  • untrusted_path – User-provided path (potentially malicious).

  • must_exist – If True, raise error if path doesn’t exist.

  • base_dir – Optional base directory to constrain resolution.

Returns:

Resolved absolute path as string (CodeQL taint-tracking compliant).

Raises:

FileNotFoundError – If must_exist=True and the path doesn’t exist. PathValidationError (traversal attempts) and SecurityError (path escapes allowed directories) from the underlying resolution propagate unchanged.