Skip to content

feat(config): site environment ingress contract & configuration sanitizer - #38

Merged
ATLURI0001 merged 1 commit into
mainfrom
feat/site-env-contract
Nov 21, 2026
Merged

ATLURI0001 merged 1 commit into
mainfrom
feat/site-env-contract

Conversation

@ATLURI0001

Copy link
Copy Markdown
Owner

Contract & Sanitization Breakdown: Site Configuration & Environment Ingress

1. Input Contract Specifications

Static site generation processes rely on environment variables for URL canonicalization, port binding, build flags, and output routing. Unsanitized ingress allows path traversal, port privilege escalation, and credential exposure in logs.

+---------------------------------------------------------------------------------------+
|                             SiteEnvironmentContract                                  |
|                                                                                       |
|  [ Environment Ingress: os.environ / Dict ]                                           |
|           |                                                                           |
|           +---> sanitize_site_url()       [ Schemes (http/s), credentials stripped ]  |
|           +---> sanitize_port()           [ Range (1-65535), privileged port block ]  |
|           +---> sanitize_environment()    [ Enum (production, staging, dev, test) ]   |
|           +---> parse_bool_flag()         [ Truthy/Falsy parsing with strict guards ] |
|           +---> sanitize_path_segment()   [ Blocks '..', absolute roots, null bytes ] |
|           +---> Masking Engine            [ Masks sensitive API keys in logging ]     |
|           |                                                                           |
|           v                                                                           |
|  [ Immutable SiteEnvironmentContract Object ] ---> to_safe_dict()                     |
+---------------------------------------------------------------------------------------+

Ingress Field Validation Schema

Field Source Keys Validation Rules Sanitization Action
site_url BUILDSITE_URL, SITE_URL Valid HTTP/HTTPS URL, valid hostname Strips trailing slash, scrubs userinfo/passwords
port BUILDSITE_PORT, PORT Integer in $[1, 65535]$, $\ge 1024$ unprivileged Casts to integer, rejects non-numeric or privileged
environment BUILDSITE_ENV, ENV, NODE_ENV Must belong to {production, staging, development, testing} Case-folded to lowercase, rejects invalid
debug BUILDSITE_DEBUG, DEBUG Standard boolean string representations Maps 1/true/yes/on $\to$ True, 0/false/no/off $\to$ False
output_dir BUILDSITE_OUTPUT_DIR, OUTPUT_DIR Relative directory path Blocks .. traversal, leading /, drive roots, null bytes
api_key BUILDSITE_API_KEY, API_KEY Arbitrary credential string Masks token in safe representations (ak_l...cdef)

2. Security Defense Mechanics

  • Credential Stripping in URLs: Protects against accidental leakage of inline basic auth credentials (https://user:pass@host/) by raising ContractValidationError.
  • Privileged Port Protection: Restricts TCP ports $< 1024$ unless explicit elevated permissions are granted via allow_privileged_ports=True.
  • Directory Traversal Neutralization: Rejects ../ components across both POSIX and Windows separators, preventing builds from overwriting system files.
  • Log Safe Dictionaries: to_safe_dict() automatically redacts API keys and secrets, preventing credential leakage in stdout/CI logs.

3. Test Matrix & Verification

  • test_parse_bool_flag_truthy_and_falsy: Asserts parsing across true/false variations and rejection of invalid types/strings.
  • test_sanitize_site_url_valid_and_normalization: Verifies root trailing slash removal, default port scrubbing, and default fallback.
  • test_sanitize_site_url_rejections: Confirms rejection of non-http schemes, userinfo credentials, and null-byte injection.
  • test_sanitize_port_bounds_and_privileged: Validates port boundary constraints and unprivileged floor enforcement.
  • test_sanitize_environment_name: Verifies environment tier normalization and error raising on unrecognized environments.
  • test_sanitize_path_segment_traversal_defense: Verifies rejection of relative path escapes and absolute root paths.
  • test_site_environment_contract_from_dict: Confirms full contract instantiation, secret masking, and safe serialization.

@ATLURI0001
ATLURI0001 merged commit a83e821 into main Nov 21, 2026
9 checks passed
@ATLURI0001
ATLURI0001 deleted the feat/site-env-contract branch November 21, 2026 15:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant