Skip to content

USL Security Overview

Last Updated: January 15, 2026
Security Contact: security@usl-lang.org
Version: 1.0.0

Introduction

USL (Universal Specification Language) is designed with security as a foundational principle. This document provides an overview of USL's security architecture, features, and best practices.

Security Philosophy

USL follows a policy-first, secure-by-default approach:

  • Zero Trust: No behavior executes without explicit authorization
  • Defense in Depth: Multiple layers of security controls
  • Fail Secure: Compilation fails on security violations
  • Least Privilege: Default deny with explicit grants
  • Transparency: All security decisions are auditable

Security Features

1. Secret Types (Secret<T>)

USL provides first-class support for sensitive data:

entity User {
  email: String
  password: Secret<Hashed>      // Never appears in logs/responses
  ssn: Secret<Encrypted>         // Encrypted at rest
  credit_card: Secret<Tokenized> // Replaced with tokens
}

Guarantees: - Secrets never leak into logs, error messages, or API responses - Compiler enforces secret flow analysis (E401-E404 errors) - Automatic redaction in generated code

2. Policy Enforcement

Mandatory authorization for all behaviors:

policy CanUpdateProfile(user: User, target: User) {
  user.id == target.id || user.role == "admin"
}

behavior UpdateProfile(user: User, target: User) {
  authorize CanUpdateProfile(user, target)
  expose Update[User]
}

Guarantees: - E301: Behavior without authorization policy fails compilation - E304: Policy totality checking (all paths authorized) - Runtime enforcement in generated code

3. Escape Validation

Escape hatches require explicit adapters:

escape ValidateEmail(email: String) -> Bool adapter "email_validator"

Guarantees: - E902: Missing adapter fails compilation - Forces explicit trust boundaries - Clear audit trail of external dependencies

4. Layer Boundaries

Compiler enforces architectural boundaries:

  • Domain Layer: Business logic only (no I/O)
  • Service Layer: Orchestration (no direct DB access)
  • Query Layer: Read-only operations
  • API Layer: Input validation and serialization

Guarantees: - E601-E608: Cross-layer violations fail compilation - E651: Query layer cannot perform writes - Clear separation of concerns

5. Proof Engines

Formal verification of security properties:

  • Policy Totality: All execution paths authorized
  • Invariants: Data integrity constraints enforced
  • Capability Safety: Resource access controlled
  • Linearity: Resources consumed exactly once

Security Testing

Test Coverage

  • 232 integration tests (100% passing)
  • 14 security-specific test suites
  • Fuzzing targets: Parser, semantic analyzer, proof engines
  • Property-based testing: QuickCheck-style generators

Fuzzing Infrastructure

Located in compiler/fuzz/:

cargo +nightly fuzz run parser_fuzzer -- -max_total_time=300
cargo +nightly fuzz run semantic_fuzzer -- -max_total_time=300
cargo +nightly fuzz run proof_fuzzer -- -max_total_time=300

CI/CD Security Checks

  • cargo audit: Dependency vulnerability scanning
  • cargo deny: License and advisory checks
  • cargo vet: Supply chain verification
  • Nightly fuzzing: Continuous security testing

Attack Surface

Inputs

  • USL Source Code: Parsed and validated (lexer + parser)
  • Import Declarations: Validated against trust policies
  • External Adapters: Require explicit registration
  • Configuration Files: Schema-validated YAML/JSON

Outputs

  • Generated Code: TypeScript, SQL, OpenAPI
  • Documentation: Markdown, HTML
  • Deployment Manifests: Docker, Kubernetes YAML

Trust Boundaries

  1. User Input → Parser: Validated by lexer/parser (E101-E199)
  2. Parser → Semantic: Type-checked and policy-verified (E201-E499)
  3. Semantic → Codegen: IR validated (E601-E699)
  4. Escape Hatches → Adapters: Explicit trust decisions (E902)
  5. Generated Code → Runtime: Validated at deploy time

Known Limitations

Current Scope

USL v1.0.0 focuses on compile-time security:

  • ✅ Input validation
  • ✅ Secret flow analysis
  • ✅ Policy enforcement at compile-time
  • ✅ Generated code security

Out of Scope (future work):

  • ❌ Runtime monitoring/alerting
  • ❌ Dynamic policy updates
  • ❌ Real-time threat detection
  • ❌ Distributed tracing

Residual Risks

  1. Adapter Security: External adapters are trusted (user responsibility)
  2. Generated Code: Security depends on runtime environment
  3. Supply Chain: Dependencies audited but not formally verified
  4. Time-of-Check/Time-of-Use: Policies checked at compile-time

Compliance

USL includes features to support:

  • GDPR: Data minimization, right to deletion, consent management
  • HIPAA: Access controls, encryption, audit logging
  • PCI-DSS: Cardholder data protection, encryption, audit trails
  • SOC 2: Security controls documentation

See compliance.md for details.

Security Documentation

Reporting Security Issues

DO NOT open public GitHub issues for security vulnerabilities.

Contact: security@usl-lang.org
PGP Key: Available at https://usl-lang.org/security/pgp-key.asc

Response Timeline: - 24 hours: Acknowledgment - 7 days: Initial assessment - 90 days: Coordinated disclosure (if applicable)

See vulnerability-disclosure.md for complete policy.

Security Roadmap

v1.1 (Q2 2026)

  • Runtime policy enforcement SDK
  • Dynamic policy updates
  • Real-time security monitoring
  • Enhanced fuzzing (corpus generation)

v1.2 (Q3 2026)

  • Formal verification of codegen correctness
  • Certified dependencies (cargo-vet integration)
  • Security dashboard (metrics + alerts)
  • SAST/DAST tool integration

v2.0 (Q4 2026)

  • Zero-knowledge proof support
  • Differential privacy primitives
  • Homomorphic encryption types
  • Secure multi-party computation

Resources

License

This security documentation is licensed under CC BY 4.0.

Version History: - v1.0.0 (2026-01-15): Initial release