Incomplete Documentation of Program Execution

Description

Incomplete Documentation of Program Execution occurs when a product's documentation fails to comprehensively describe all mechanisms that control or influence how programs execute. This includes missing documentation for environment variables, configuration files, registry keys, command-line switches, system settings, startup parameters, and other execution-influencing factors. Without complete execution documentation, administrators and security personnel cannot properly configure, secure, or audit the system.

Risk

Incomplete program execution documentation has indirect security implications. Hidden configuration options may have security implications that aren't understood. Environment variables affecting security behavior may not be properly set. Command-line options that bypass security controls may not be documented. Undocumented execution modes may have different security characteristics. Attackers may discover undocumented execution controls before defenders. Incident response is hindered without knowing all execution factors. Security hardening guides cannot be complete without this information.

Solution

Document all environment variables that affect program behavior. Document all configuration files, their locations, and their options. Document all command-line switches and their security implications. Document startup sequences and initialization procedures. Document all external factors that influence execution. Include security implications for each execution control. Maintain documentation as new execution controls are added. Test that documented execution controls work as described.

Common Consequences

Impact	Details
Other	Scope: Other Reduce Maintainability - Cannot properly maintain or configure the system.
Other	Scope: Other Increase Analytical Complexity - Security analysis cannot cover undocumented execution factors.
Confidentiality	Scope: Confidentiality Information Exposure - Undocumented debug modes may expose sensitive information.

Example Code

Vulnerable Code

// Vulnerable: Program with undocumented execution controls

// FILE: main.py
// No documentation for:
// - Environment variables that affect behavior
// - Hidden command-line options
// - Debug modes
// - Configuration file locations

import os
import sys

def main():
    # Undocumented: DEBUG environment variable
    if os.environ.get('DEBUG'):
        enable_debug_mode()  # Logs sensitive data, disables auth!

    # Undocumented: SKIP_AUTH environment variable
    if os.environ.get('SKIP_AUTH'):
        bypass_authentication()  # Security bypass!

    # Undocumented: --insecure command-line flag
    if '--insecure' in sys.argv:
        disable_tls_verification()  # Man-in-middle vulnerability!

    # Undocumented: alternative config file locations
    config_paths = [
        os.environ.get('CONFIG_FILE'),  # Undocumented
        '/etc/app/config.yaml',
        '~/.app/config.yaml',
        './config.yaml',  # Could be attacker-controlled!
    ]

    for path in config_paths:
        if path and os.path.exists(path):
            load_config(path)
            break


// FILE: server.py
// Missing documentation for server execution options

class Server:
    def __init__(self):
        # Undocumented: BIND_ALL environment variable
        if os.environ.get('BIND_ALL'):
            self.host = '0.0.0.0'  # Binds to all interfaces!
        else:
            self.host = '127.0.0.1'

        # Undocumented: --no-rate-limit flag
        if '--no-rate-limit' in sys.argv:
            self.rate_limiting = False  # DoS vulnerability!

        # Undocumented: LOG_PASSWORDS for "debugging"
        if os.environ.get('LOG_PASSWORDS'):
            self.log_passwords = True  # Massive security issue!


// FILE: config_loader.py
// No documentation about config precedence and security implications

def load_all_configs():
    """
    Loads configuration with undocumented precedence:
    1. Command-line args (override all)
    2. Environment variables
    3. User config file (~/.apprc)  # Undocumented!
    4. System config (/etc/app.conf)
    5. Built-in defaults

    Undocumented: Environment variables can disable security features!
    """
    pass

Fixed Code

// Fixed: Complete documentation of program execution

/*
 * ============================================================================
 * PROGRAM EXECUTION DOCUMENTATION
 * ============================================================================
 *
 * This document describes ALL mechanisms that control program execution.
 *
 * 1. ENVIRONMENT VARIABLES
 * ========================
 *
 * Variable          | Type    | Default | Description
 * ------------------|---------|---------|----------------------------------
 * APP_CONFIG_PATH   | path    | (none)  | Override config file location
 * APP_LOG_LEVEL     | string  | "INFO"  | Logging verbosity (DEBUG,INFO,WARN,ERROR)
 * APP_PORT          | integer | 8080    | Server listening port
 * APP_HOST          | string  | "127.0.0.1" | Server bind address
 * APP_TLS_CERT      | path    | (none)  | TLS certificate path
 * APP_TLS_KEY       | path    | (none)  | TLS private key path
 *
 * Security-Sensitive Environment Variables:
 * -----------------------------------------
 * These variables affect security and should be carefully controlled:
 *
 * APP_DEBUG         | boolean | false   | Enable debug mode
 *                   |         |         | WARNING: Logs may contain sensitive data
 *                   |         |         | NEVER enable in production!
 *
 * APP_INSECURE_DEV  | boolean | false   | Disable security checks (development only)
 *                   |         |         | WARNING: Completely bypasses authentication
 *                   |         |         | NEVER set in production!
 *
 * 2. COMMAND-LINE OPTIONS
 * =======================
 *
 * Usage: app [options]
 *
 * General Options:
 *   -c, --config PATH    Configuration file path (default: /etc/app/config.yaml)
 *   -p, --port PORT      Server port (default: 8080)
 *   -h, --help           Show this help message
 *   -v, --version        Show version information
 *
 * Security Options:
 *   --tls-cert PATH      Path to TLS certificate (required for HTTPS)
 *   --tls-key PATH       Path to TLS private key (required for HTTPS)
 *   --require-auth       Require authentication for all endpoints (default: true)
 *
 * Development Options (DO NOT USE IN PRODUCTION):
 *   --debug              Enable debug mode (verbose logging, may expose secrets)
 *   --no-tls-verify      Disable TLS certificate verification (INSECURE)
 *   --skip-auth          Skip authentication (COMPLETELY INSECURE)
 *
 * 3. CONFIGURATION FILES
 * ======================
 *
 * Configuration files are loaded in the following order (later overrides earlier):
 *
 * 1. /etc/app/defaults.yaml      - System defaults (read-only)
 * 2. /etc/app/config.yaml        - System configuration (admin-controlled)
 * 3. ~/.config/app/config.yaml   - User configuration (user-controlled)
 * 4. ./config.yaml               - Local override (SECURITY WARNING: See below)
 * 5. $APP_CONFIG_PATH            - Environment override
 * 6. Command-line arguments      - Highest priority
 *
 * SECURITY WARNING: Local config file (./config.yaml):
 * - This file is loaded from the current working directory
 * - An attacker with write access to the CWD could inject malicious config
 * - For security-sensitive deployments, run from a protected directory
 * - Or use --no-local-config to disable this behavior
 *
 * 4. INITIALIZATION SEQUENCE
 * ==========================
 *
 * 1. Parse command-line arguments
 * 2. Load environment variables
 * 3. Load configuration files (in precedence order)
 * 4. Initialize logging (security events always logged)
 * 5. Validate configuration
 * 6. Initialize security modules
 * 7. Start server
 *
 * 5. SECURITY IMPLICATIONS SUMMARY
 * =================================
 *
 * Feature              | Risk Level | Notes
 * ---------------------|------------|----------------------------------
 * Debug mode           | HIGH       | May log secrets, disable security
 * --skip-auth          | CRITICAL   | Completely bypasses authentication
 * --no-tls-verify      | HIGH       | Enables MITM attacks
 * Local config file    | MEDIUM     | May be attacker-controlled
 * APP_INSECURE_DEV     | CRITICAL   | Disables all security checks
 *
 */

// Implementation follows documented behavior

import os
import sys
import argparse
from typing import Optional


# Documented configuration class
class AppConfig:
    """
    Application configuration with fully documented execution controls.

    See: docs/EXECUTION.md for complete documentation of all options.

    Attributes:
        config_path: Path to configuration file
        port: Server listening port (1-65535)
        host: Server bind address
        debug: Debug mode (WARNING: security implications - see docs)
        tls_cert: Path to TLS certificate
        tls_key: Path to TLS private key
        require_auth: Whether authentication is required
    """

    # Documented environment variable names
    ENV_CONFIG_PATH = 'APP_CONFIG_PATH'
    ENV_LOG_LEVEL = 'APP_LOG_LEVEL'
    ENV_PORT = 'APP_PORT'
    ENV_HOST = 'APP_HOST'
    ENV_DEBUG = 'APP_DEBUG'  # SECURITY: See documentation

    def __init__(self):
        self.config_path: Optional[str] = None
        self.port: int = 8080
        self.host: str = '127.0.0.1'
        self.debug: bool = False
        self.tls_cert: Optional[str] = None
        self.tls_key: Optional[str] = None
        self.require_auth: bool = True

    @classmethod
    def from_environment(cls) -> 'AppConfig':
        """
        Load configuration from environment variables.

        Documented environment variables:
        - APP_CONFIG_PATH: Override config file location
        - APP_LOG_LEVEL: Logging verbosity
        - APP_PORT: Server port
        - APP_HOST: Bind address
        - APP_DEBUG: Enable debug mode (SECURITY WARNING)

        Returns:
            AppConfig instance with environment values applied
        """
        config = cls()

        config.config_path = os.environ.get(cls.ENV_CONFIG_PATH)
        config.port = int(os.environ.get(cls.ENV_PORT, '8080'))
        config.host = os.environ.get(cls.ENV_HOST, '127.0.0.1')
        config.debug = os.environ.get(cls.ENV_DEBUG, '').lower() == 'true'

        if config.debug:
            import warnings
            warnings.warn(
                "Debug mode enabled via APP_DEBUG. "
                "This may log sensitive data. "
                "Do not use in production!",
                SecurityWarning
            )

        return config


def create_argument_parser() -> argparse.ArgumentParser:
    """
    Create argument parser with fully documented options.

    All options are documented in the help text and in EXECUTION.md.
    """
    parser = argparse.ArgumentParser(
        description='Application Server',
        epilog='See docs/EXECUTION.md for complete documentation'
    )

    parser.add_argument(
        '-c', '--config',
        help='Configuration file path (default: /etc/app/config.yaml)'
    )

    parser.add_argument(
        '-p', '--port',
        type=int,
        default=8080,
        help='Server port (default: 8080)'
    )

    parser.add_argument(
        '--debug',
        action='store_true',
        help='Enable debug mode. SECURITY WARNING: May log sensitive data!'
    )

    parser.add_argument(
        '--skip-auth',
        action='store_true',
        help='Skip authentication. SECURITY WARNING: Completely insecure! '
             'Only use for local development.'
    )

    return parser

CVE Examples

This CWE is marked as PROHIBITED for direct CVE mapping as it represents a documentation quality concern rather than a direct security vulnerability.

CWE-1059: Insufficient Technical Documentation (parent)
CWE-1225: Documentation Issues (category member)
CWE-1110: Incomplete Design Documentation (related)
CWE-1111: Incomplete I/O Documentation (related)

References

MITRE Corporation. "CWE-1112: Incomplete Documentation of Program Execution." https://cwe.mitre.org/data/definitions/1112.html

Incomplete Documentation of Program Execution

Description

Risk

Solution

Common Consequences

Example Code

Vulnerable Code

Fixed Code

CVE Examples

References

Platform

Resources

Company

Latest Articles

Incomplete Documentation of Program Execution

Description

Risk

Solution

Common Consequences

Example Code

Vulnerable Code

Fixed Code

CVE Examples

Related CWEs

References