Security Audit#

Keywords: security report, vulnerability audit, security hardening, audit log, security features

Asok includes built-in security measures. This document summarizes the protections integrated into the framework to help protect applications from common web vulnerabilities.

Executive Summary#

Asok includes modern security protections by default. In most cases, you do not need to write security-specific code to get baseline protection against SQL injection, XSS, CSRF, and related issues.

1. Protection Against Injections#

SQL Injection#

The Asok ORM uses parameterized queries for all data interactions. User input is never concatenated directly into SQL strings. - All Query methods (where, where_in, etc.) use ? placeholders. - Column names are strictly validated against model metadata.

Cross-Site Scripting (XSS)#

The Asok template engine implements automatic HTML escaping by default. - Any variable rendered via {{ user_input }} is escaped (e.g., < becomes <). - To render raw HTML, you must explicitly use the |safe filter or the SafeString class.

2. Broken Access Control#

CSRF Protection#

Asok uses the Double Submit Cookie pattern to prevent Cross-Site Request Forgery. - All state-changing requests (POST, PUT, DELETE) must include a csrf_token. - The token is verified against an HttpOnly cookie. - Use {{ request.csrf_input() }} in your forms to automatically include the token.

Mass Assignment#

The ORM protects sensitive fields from being updated in bulk from user input. - Fields marked as protected in your Model are ignored by Model.create() and Model.update() unless the _trust=True flag is passed.

3. Authentication & Sessions#

Password Storage#

Asok uses PBKDF2-SHA256 with 600,000 iterations for password hashing. This is handled automatically by Field.Password().

Session Security#

• Secure IDs: Session identifiers are 32-byte cryptographically strong hex strings (secrets.token_urlsafe(32)).
• Cookie Security:
• Session cookies are HttpOnly and SameSite=Strict by default
• Secure flag added automatically on HTTPS
• CSRF cookies also use HttpOnly and SameSite=Strict for maximum protection
• HMAC Signing: Session IDs are signed with HMAC to prevent tampering
• Rotation: IDs can be rotated using session.regenerate() to prevent session fixation
• CSRF Token Rotation: CSRF tokens are automatically rotated after successful validation to prevent token reuse attacks

4. File and URL Safety#

File Upload Validation ⭐ NEW in v0.1.6#

Asok provides automatic MIME type validation using magic bytes detection to prevent malicious file uploads:

• Magic Bytes Detection: Files are validated by their actual content (first bytes), not just extension
• 50+ Formats Supported: Images (JPEG, PNG, GIF, WebP, BMP, TIFF, SVG), Audio (MP3, WAV, FLAC, OGG, AAC), Video (MP4, WebM, MKV, AVI, MOV), Documents (PDF, ZIP, Office files)
• Extension Matching: File extension must match the detected MIME type
• Whitelist Enforcement: allowed_types parameter enforces strict MIME type whitelist
• Secure Filenames: Files are renamed with UUID by default (secure_filename=True)
• Restrictive Permissions: Saved files get 0o644 (rw-r--r--) permissions
• Security Warnings: Logs warning if validation is disabled or no whitelist specified

# Secure file upload with validation
photo.save("uploads/", allowed_types=['image/jpeg', 'image/png'])

See File Storage for complete documentation.

Path Traversal#

The secure_filename() utility is used automatically during file uploads to remove directory separators and illegal characters, ensuring files cannot be saved outside the intended directory.

Enhanced in v0.1.6: - Uses pathlib.Path.resolve(strict=True) for robust path resolution - Validates all parent directories for symlinks - Only accepts filename (basename) to prevent any path traversal - Returns 403 Forbidden on escape attempts

Open Redirects#

The request.redirect() method uses is_safe_url() to block redirects to external domains or malformed URLs that could be used for phishing.

5. Security Headers#

Asok automatically injects a set of "best-practice" security headers into every HTTP response:

6. Content Security Policy (CSP)#

Asok provides built-in support for Nonces. You can access a unique cryptographic nonce for the current request via request.nonce.

<script nonce="{{ request.nonce }}">
  // This inline script is authorized by the CSP
</script>

7. Security Audit Results (v0.3.0)#

The following notes summarize the main security mechanisms currently implemented in Asok v0.3.0:

SQL Injection Protection ✅#

• Parameterized Queries: All ORM queries use ? placeholders with separate arguments array.
• Strict Column Validation: _valid_column() strictly validates all column names against model metadata, preventing injection in non-parameterizable clauses.
• Operator Whitelist: SQL operators are validated against a strict _OPERATORS whitelist.

XSS Protection ✅#

• Auto-Escaping: All template variables are automatically escaped via _escape().
• UI Attribute Escaping: The centralized _render_attrs utility ensures all HTML attributes (including nested ones like dropdown__class) are properly escaped.
• SafeString Class: Explicit opt-in required for raw HTML via SafeString class or |safe filter.

CSRF Protection ✅#

• Cryptographic Tokens: 32-byte random tokens via secrets.token_hex(32).
• HMAC Validation: Token comparison uses hmac.compare_digest() to prevent timing attacks.
• Strict Origin Verification: For HTTPS requests, both Origin and Referer headers are validated against the host to prevent cross-origin state changes.
• SameSite Cookies: CSRF cookies use SameSite=Strict for maximum protection.

Server-Side Template Injection (SSTI) Protection ✅#

• Restricted Execution: Templates are executed in a restricted namespace with __builtins__ blocked.
• Sandbox Escape Prevention: Access to dangerous Python attributes (__class__, __globals__, __subclasses__, etc.) is strictly blocked.
• Safe Attribute Whitelist: Only a specific set of safe underscore attributes (like _table or _fields for internal needs) are accessible.

Path Traversal Protection ✅#

• Absolute Path Validation: Uses os.path.abspath() with startswith() checks
• Symlink Protection: Uses os.path.realpath() and os.path.islink() to prevent symlink traversal attacks
• Safe Resolve Function: _safe_resolve() utility ensures paths stay within allowed directories
• 403 on Escape Attempts: Returns 403 Forbidden if path traversal is detected
• Static File Validation: All static file serving validates paths before reading

Password Security ✅#

• PBKDF2-SHA256: Industry-standard password hashing algorithm
• High Iteration Count: 600,000 iterations (OWASP 2023 compliant)
• Random Salt: Each password gets a unique 16-byte random salt
• Secure Format: Stored as pbkdf2:sha256:600000$salt$hash

Session & Cookie Security ✅#

• HttpOnly Flag: All sensitive cookies (session, CSRF, flash) have HttpOnly
• Secure Flag: Automatically added for HTTPS connections
• SameSite=Strict: Session and CSRF cookies use Strict for best protection
• SameSite=Lax: Non-sensitive cookies (language) use Lax appropriately
• HMAC Signing: Session IDs are signed to prevent tampering
• Secure RNG: Uses secrets module for cryptographically secure random generation.

Data Encryption (GDPR / PCI-DSS) ✅#

Asok provides a native Field.EncryptedString() for storing sensitive data (SSNs, credit card numbers, phone numbers, API keys) transparently encrypted in the database.

• Algorithm: AES-256 via the cryptography package's Fernet engine (authenticated encryption — also protects integrity).
• Key Derivation: The encryption key is derived from the application's SECRET_KEY using SHA-256, then base64url-encoded to produce a valid 32-byte Fernet key.
• Transparent: Values are automatically encrypted on save() and decrypted on __init__() (when loading from the DB). Application code always sees plaintext.
• Graceful Degradation: If decryption fails (e.g., key rotation or mismatch), the method returns the raw ciphertext instead of crashing, and logs an error for investigation.
• Non-queryable by design: Fernet tokens are non-deterministic (ciphertext differs each time), so direct database queries or indexes on encrypted columns are not possible — by design.

from asok import Model, Field

class Customer(Model):
    name = Field.String()
    ssn  = Field.EncryptedString()   # Encrypted transparently

c = Customer.create(name="Alice", ssn="123-45-6789")
print(c.ssn)  # "123-45-6789" — plaintext in Python
# In the DB: "gAAAAAB..." — Fernet ciphertext

[!IMPORTANT] The cryptography library must be installed: pip install "asok[security]"

Zero-Eval Content Security Policy ✅#

• Least Privilege Principle: Asok implements a Content Security Policy that completely disables 'unsafe-eval' by default in production.
• Zero-Eval Reactive Architecture: Thanks to server-side precompilation of reactive expressions and dynamic registry injection via cryptographically nonced script elements, the browser never uses eval() or new Function().
• Granular Control: Developers can still force 'unsafe-eval' if they use third-party libraries requiring it via CSP_UNSAFE_EVAL.

Command Injection Protection ✅#

• No Runtime Execution: No os.system(), eval(), or exec() in runtime code
• Subprocess Limited: subprocess only used in CLI tools and secure background optimization, never directly exposed to request routing.
• Subprocess Confinement: The image optimizer utility in asok/utils/image.py strictly restricts binary execution pathways inside the .asok/bin subdirectory using os.path.commonpath checks, preventing path traversal or execution of unauthorized binaries.
• No Dynamic Code: No dynamic code execution from user input

Log Injection Protection ✅#

• Newline Sanitization: \n and \r characters removed from logged request data
• Structured Logging: JSON format option for production with proper escaping
• Limited Debug Info: Debug logs never expose sensitive session data or passwords

Validation & Input Handling ✅#

• Type Validation: Strong type checking via Field types
• Email Validation: RFC-compliant email validation
• URL Validation: Validates URL format and scheme
• HTML Sanitization: Optional bleach integration for HTML whitelisting

Security Summary#

Conclusion#

Asok provides secure defaults and layered defenses against common web vulnerabilities. As with any framework, applications still need sensible configuration, safe templates, and careful access control.