oscura 0.5.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

oscura/cli/completion.py

@@ -0,0 +1,250 @@
+"""Shell completion support for Oscura CLI.
+
+Generates completion scripts for bash, zsh, and fish shells.
+
+
+Example:
+    $ oscura --install-completion bash
+    $ oscura --show-completion bash > ~/.bash_completion.d/oscura
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+def get_completion_script(shell: str) -> str:
+    """Get completion script for specified shell.
+
+    Args:
+        shell: Shell type ('bash', 'zsh', or 'fish').
+
+    Returns:
+        Completion script content.
+
+    Raises:
+        ValueError: If shell type is unsupported.
+    """
+    if shell == "bash":
+        return _get_bash_completion()
+    elif shell == "zsh":
+        return _get_zsh_completion()
+    elif shell == "fish":
+        return _get_fish_completion()
+    else:
+        raise ValueError(f"Unsupported shell: {shell}")
+
+
+def install_completion(shell: str) -> Path:
+    """Install completion script for specified shell.
+
+    Args:
+        shell: Shell type ('bash', 'zsh', or 'fish').
+
+    Returns:
+        Path where completion was installed.
+
+    Raises:
+        ValueError: If shell type is unsupported.
+    """
+    script = get_completion_script(shell)
+    home = Path.home()
+
+    if shell == "bash":
+        completion_dir = home / ".bash_completion.d"
+        completion_dir.mkdir(exist_ok=True)
+        completion_file = completion_dir / "oscura"
+    elif shell == "zsh":
+        completion_dir = home / ".zsh" / "completion"
+        completion_dir.mkdir(parents=True, exist_ok=True)
+        completion_file = completion_dir / "_oscura"
+    elif shell == "fish":
+        completion_dir = home / ".config" / "fish" / "completions"
+        completion_dir.mkdir(parents=True, exist_ok=True)
+        completion_file = completion_dir / "oscura.fish"
+    else:
+        raise ValueError(f"Unsupported shell: {shell}")
+
+    with open(completion_file, "w") as f:
+        f.write(script)
+
+    return completion_file
+
+
+def _get_bash_completion() -> str:
+    """Get bash completion script."""
+    return """# Bash completion for oscura
+
+_oscura_completion() {
+    local cur prev opts
+    COMPREPLY=()
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+    # Main commands
+    local commands="analyze decode export visualize benchmark validate config plugins characterize batch compare shell tutorial"
+
+    # Global options
+    local global_opts="--help --version --verbose --quiet --config --json"
+
+    # If we're on the first argument, complete commands or global options
+    if [[ ${COMP_CWORD} -eq 1 ]]; then
+        COMPREPLY=( $(compgen -W "${commands} ${global_opts}" -- ${cur}) )
+        return 0
+    fi
+
+    # Get the command
+    local cmd="${COMP_WORDS[1]}"
+
+    # Command-specific completions
+    case "${cmd}" in
+        analyze|decode|export|visualize)
+            # Complete file paths and help
+            if [[ ${cur} == -* ]]; then
+                COMPREPLY=( $(compgen -W "--help" -- ${cur}) )
+            else
+                COMPREPLY=( $(compgen -f -X '!*.@(wfm|vcd|csv|pcap|wav)' -- ${cur}) )
+            fi
+            ;;
+        config)
+            local config_opts="--show --set --edit --init --path --help"
+            COMPREPLY=( $(compgen -W "${config_opts}" -- ${cur}) )
+            ;;
+        plugins)
+            local plugin_cmds="list info install remove update"
+            if [[ ${COMP_CWORD} -eq 2 ]]; then
+                COMPREPLY=( $(compgen -W "${plugin_cmds}" -- ${cur}) )
+            fi
+            ;;
+        *)
+            # Default to --help for other commands
+            if [[ ${cur} == -* ]]; then
+                COMPREPLY=( $(compgen -W "--help" -- ${cur}) )
+            fi
+            ;;
+    esac
+}
+
+complete -F _oscura_completion oscura
+"""
+
+
+def _get_zsh_completion() -> str:
+    """Get zsh completion script."""
+    return """#compdef oscura
+
+_oscura() {
+    local -a commands
+    commands=(
+        'analyze:Run full analysis workflow'
+        'decode:Decode protocol data'
+        'export:Export analysis results'
+        'visualize:Launch interactive viewer'
+        'benchmark:Run performance benchmarks'
+        'validate:Validate protocol specification'
+        'config:Manage configuration'
+        'plugins:Manage plugins'
+        'characterize:Characterize signal'
+        'batch:Batch process files'
+        'compare:Compare signals'
+        'shell:Start interactive shell'
+        'tutorial:Run interactive tutorial'
+    )
+
+    local -a file_args
+    file_args=(
+        '*:waveform file:_files -g "*.{wfm,vcd,csv,pcap,wav}"'
+    )
+
+    _arguments -C \\
+        '(-h --help)'{-h,--help}'[Show help message]' \\
+        '(-v --verbose)'{-v,--verbose}'[Increase verbosity]' \\
+        '--config[Configuration file]:config file:_files' \\
+        '(-q --quiet)'{-q,--quiet}'[Quiet mode]' \\
+        '--json[JSON output mode]' \\
+        '1: :->command' \\
+        '*:: :->args'
+
+    case $state in
+        command)
+            _describe -t commands 'oscura commands' commands
+            ;;
+        args)
+            case $words[1] in
+                analyze|decode|visualize)
+                    _files -g "*.{wfm,vcd,csv,pcap,wav}"
+                    ;;
+                config)
+                    _arguments \\
+                        '--show[Show configuration]' \\
+                        '--set[Set value]:key=value:' \\
+                        '--edit[Edit configuration]' \\
+                        '--init[Initialize configuration]' \\
+                        '--path[Show config path]'
+                    ;;
+            esac
+            ;;
+    esac
+}
+
+_oscura
+"""
+
+
+def _get_fish_completion() -> str:
+    """Get fish completion script."""
+    return """# Fish completion for oscura
+
+# Main commands
+complete -c oscura -n "__fish_use_subcommand" -a analyze -d "Run full analysis workflow"
+complete -c oscura -n "__fish_use_subcommand" -a decode -d "Decode protocol data"
+complete -c oscura -n "__fish_use_subcommand" -a export -d "Export analysis results"
+complete -c oscura -n "__fish_use_subcommand" -a visualize -d "Launch interactive viewer"
+complete -c oscura -n "__fish_use_subcommand" -a benchmark -d "Run performance benchmarks"
+complete -c oscura -n "__fish_use_subcommand" -a validate -d "Validate protocol specification"
+complete -c oscura -n "__fish_use_subcommand" -a config -d "Manage configuration"
+complete -c oscura -n "__fish_use_subcommand" -a plugins -d "Manage plugins"
+complete -c oscura -n "__fish_use_subcommand" -a characterize -d "Characterize signal"
+complete -c oscura -n "__fish_use_subcommand" -a batch -d "Batch process files"
+complete -c oscura -n "__fish_use_subcommand" -a compare -d "Compare signals"
+complete -c oscura -n "__fish_use_subcommand" -a shell -d "Start interactive shell"
+complete -c oscura -n "__fish_use_subcommand" -a tutorial -d "Run interactive tutorial"
+
+# Global options
+complete -c oscura -s h -l help -d "Show help message"
+complete -c oscura -s v -l verbose -d "Increase verbosity"
+complete -c oscura -s q -l quiet -d "Quiet mode"
+complete -c oscura -l config -d "Configuration file" -r
+complete -c oscura -l json -d "JSON output mode"
+
+# analyze subcommand
+complete -c oscura -n "__fish_seen_subcommand_from analyze" -l protocol -d "Protocol hint"
+complete -c oscura -n "__fish_seen_subcommand_from analyze" -l export-dir -d "Export directory" -r
+complete -c oscura -n "__fish_seen_subcommand_from analyze" -s i -l interactive -d "Interactive mode"
+complete -c oscura -n "__fish_seen_subcommand_from analyze" -l output -d "Output format" -a "json csv html table"
+
+# decode subcommand
+complete -c oscura -n "__fish_seen_subcommand_from decode" -l protocol -d "Protocol type" -a "uart spi i2c can auto"
+complete -c oscura -n "__fish_seen_subcommand_from decode" -l baud-rate -d "Baud rate" -r
+complete -c oscura -n "__fish_seen_subcommand_from decode" -l show-errors -d "Show only errors"
+
+# config subcommand
+complete -c oscura -n "__fish_seen_subcommand_from config" -l show -d "Show configuration"
+complete -c oscura -n "__fish_seen_subcommand_from config" -l set -d "Set value" -r
+complete -c oscura -n "__fish_seen_subcommand_from config" -l edit -d "Edit configuration"
+complete -c oscura -n "__fish_seen_subcommand_from config" -l init -d "Initialize configuration"
+complete -c oscura -n "__fish_seen_subcommand_from config" -l path -d "Show config path"
+
+# File completions for commands that take file arguments
+for cmd in analyze decode visualize export
+    complete -c oscura -n "__fish_seen_subcommand_from $cmd" -F -a '(__fish_complete_suffix .wfm .vcd .csv .pcap .wav)'
+end
+"""
+
+
+if __name__ == "__main__":
+    # Allow running as: python -m oscura.cli.completion bash
+    if len(sys.argv) > 1:
+        shell_type = sys.argv[1]
+        print(get_completion_script(shell_type))

oscura/cli/config_cmd.py

@@ -0,0 +1,361 @@
+"""Oscura Config Command - Configuration Management.
+
+Provides CLI for viewing and editing Oscura configuration.
+
+
+Example:
+    $ oscura config --show
+    $ oscura config --set analysis.default_protocol=uart
+    $ oscura config --edit
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shlex
+import subprocess
+from pathlib import Path
+from typing import Any
+
+import click
+
+logger = logging.getLogger("oscura.cli.config")
+
+# Allowlist of trusted editors (SEC-004 fix)
+ALLOWED_EDITORS = {
+    "nano",
+    "vim",
+    "vi",
+    "emacs",
+    "nvim",
+    "code",
+    "subl",
+    "atom",
+    "gedit",
+    "kate",
+    "micro",
+    "helix",
+}
+
+
+def _get_safe_editor() -> str:
+    """Get validated editor from environment.
+
+    Returns:
+        Safe editor command.
+
+    Security:
+        SEC-004 fix: Validates editor against allowlist to prevent command injection
+        via $EDITOR environment variable. Falls back to 'nano' for untrusted editors.
+
+    Example:
+        >>> os.environ["EDITOR"] = "vim"
+        >>> editor = _get_safe_editor()
+        >>> assert editor == "vim"
+
+        >>> os.environ["EDITOR"] = "rm -rf /"
+        >>> editor = _get_safe_editor()
+        >>> assert editor == "nano"  # Fallback to safe default
+
+    References:
+        https://owasp.org/www-project-top-ten/
+    """
+    editor_env = os.environ.get("EDITOR", "nano")
+
+    # Check for command substitution and newlines before parsing
+    # These are shell injection attempts that shlex may not detect
+    if "`" in editor_env or "$(" in editor_env or "\n" in editor_env or "\r" in editor_env:
+        logger.warning(
+            "Command substitution or newline detected in EDITOR, falling back to nano for safety"
+        )
+        return "nano"
+
+    # Extract base command (handle args like "code --wait")
+    try:
+        editor_parts = shlex.split(editor_env)
+        if not editor_parts:
+            logger.warning("Empty EDITOR value, using nano")
+            return "nano"
+
+        editor_cmd = Path(editor_parts[0]).name
+    except ValueError as e:
+        logger.warning(f"Invalid EDITOR value '{editor_env}': {e}, using nano")
+        return "nano"
+
+    # Validate against allowlist
+    if editor_cmd not in ALLOWED_EDITORS:
+        logger.warning(
+            f"Untrusted editor '{editor_cmd}' not in allowlist, falling back to nano. "
+            f"Allowed editors: {', '.join(sorted(ALLOWED_EDITORS))}"
+        )
+        return "nano"
+
+    # Check for shell metacharacters that indicate command injection attempts
+    # Shell metacharacters parsed as separate tokens by shlex indicate injection
+    shell_metacharacters = {"&&", "||", ";", "|", ">", "<", ">>", "<<", "&"}
+    if len(editor_parts) > 1 and any(part in shell_metacharacters for part in editor_parts[1:]):
+        logger.warning(
+            f"Shell metacharacters detected in EDITOR '{editor_env}', "
+            f"falling back to nano for safety"
+        )
+        return "nano"
+
+    return editor_env  # Return full command with args if valid
+
+
+@click.command()
+@click.option(
+    "--show",
+    is_flag=True,
+    help="Show current configuration.",
+)
+@click.option(
+    "--set",
+    "set_value",
+    type=str,
+    default=None,
+    help="Set configuration value (key=value).",
+)
+@click.option(
+    "--edit",
+    is_flag=True,
+    help="Open configuration file in editor.",
+)
+@click.option(
+    "--init",
+    is_flag=True,
+    help="Initialize default configuration file.",
+)
+@click.option(
+    "--path",
+    is_flag=True,
+    help="Show configuration file path.",
+)
+@click.pass_context
+def config(
+    ctx: click.Context,
+    show: bool,
+    set_value: str | None,
+    edit: bool,
+    init: bool,
+    path: bool,
+) -> None:
+    """Manage Oscura configuration.
+
+    View, edit, and initialize configuration files.
+
+    Args:
+        ctx: Click context object.
+        show: Show configuration.
+        set_value: Set configuration value.
+        edit: Edit configuration file.
+        init: Initialize configuration.
+        path: Show config path.
+
+    Examples:
+
+        \b
+        # Show current config
+        $ oscura config --show
+
+        \b
+        # Set a value
+        $ oscura config --set analysis.default_protocol=uart
+
+        \b
+        # Edit config file
+        $ oscura config --edit
+
+        \b
+        # Initialize config
+        $ oscura config --init
+    """
+    verbose = ctx.obj.get("verbose", 0)
+
+    try:
+        config_path = _get_config_path()
+
+        if path:
+            click.echo(f"Configuration file: {config_path}")
+            return
+
+        if init:
+            _initialize_config(config_path)
+            click.echo(f"Initialized configuration at: {config_path}")
+            return
+
+        if show:
+            _show_config(config_path)
+            return
+
+        if set_value:
+            _set_config_value(config_path, set_value)
+            click.echo(f"Updated configuration: {set_value}")
+            return
+
+        if edit:
+            _edit_config(config_path)
+            return
+
+        # No options provided, show help
+        click.echo(ctx.get_help())
+
+    except Exception as e:
+        logger.error(f"Config operation failed: {e}")
+        if verbose > 1:
+            raise
+        click.echo(f"Error: {e}", err=True)
+        ctx.exit(1)
+
+
+def _get_config_path() -> Path:
+    """Get configuration file path.
+
+    Returns:
+        Path to configuration file (absolute path).
+    """
+    # Check for local config first
+    local_config = Path(".oscura.yaml").resolve()
+    if local_config.exists():
+        return local_config
+
+    # Use user config
+    user_config = Path.home() / ".config" / "oscura" / "config.yaml"
+    return user_config
+
+
+def _initialize_config(config_path: Path) -> None:
+    """Initialize default configuration file.
+
+    Args:
+        config_path: Path to configuration file.
+    """
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    default_config = """# Oscura Configuration
+
+analysis:
+  default_protocol: auto
+  auto_detect_threshold: 0.7
+  max_packets: 10000
+
+export:
+  default_format: json
+  output_dir: oscura_output
+
+visualization:
+  default_backend: matplotlib
+  figure_size: [12, 6]
+  dpi: 100
+
+cli:
+  color_output: true
+  progress_bars: true
+
+logging:
+  level: WARNING
+  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+"""
+
+    with open(config_path, "w") as f:
+        f.write(default_config)
+
+
+def _show_config(config_path: Path) -> None:
+    """Show configuration.
+
+    Args:
+        config_path: Path to configuration file.
+    """
+    if not config_path.exists():
+        click.echo("No configuration file found. Use --init to create one.")
+        return
+
+    import yaml
+
+    with open(config_path) as f:
+        config = yaml.safe_load(f)
+
+    click.echo(f"\nConfiguration ({config_path}):\n")
+    click.echo(yaml.dump(config, default_flow_style=False))
+
+
+def _set_config_value(config_path: Path, set_value: str) -> None:
+    """Set configuration value.
+
+    Args:
+        config_path: Path to configuration file.
+        set_value: Value to set (key=value format).
+    """
+    import yaml
+
+    if "=" not in set_value:
+        raise ValueError("Invalid format. Use: key=value")
+
+    key, value = set_value.split("=", 1)
+    keys = key.split(".")
+
+    # Load existing config
+    config: dict[str, Any] = {}
+    if config_path.exists():
+        with open(config_path) as f:
+            config = yaml.safe_load(f) or {}
+
+    # Set nested value
+    current = config
+    for k in keys[:-1]:
+        if k not in current:
+            current[k] = {}
+        current = current[k]
+
+    # Try to parse value
+    try:
+        # Try as number
+        if "." in value:
+            parsed_value: Any = float(value)
+        else:
+            parsed_value = int(value)
+    except ValueError:
+        # Try as boolean
+        if value.lower() in ["true", "false"]:
+            parsed_value = value.lower() == "true"
+        else:
+            # Keep as string
+            parsed_value = value
+
+    current[keys[-1]] = parsed_value
+
+    # Save config
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(config_path, "w") as f:
+        yaml.dump(config, f, default_flow_style=False)
+
+
+def _edit_config(config_path: Path) -> None:
+    """Edit configuration file with safe editor validation.
+
+    Args:
+        config_path: Path to configuration file.
+
+    Security:
+        SEC-004 fix: Uses _get_safe_editor() to validate $EDITOR against allowlist,
+        preventing command injection attacks via malicious editor values.
+
+    Raises:
+        RuntimeError: If editor execution fails.
+    """
+    # Create if doesn't exist
+    if not config_path.exists():
+        _initialize_config(config_path)
+
+    # Get validated editor (SEC-004 fix)
+    editor_cmd = _get_safe_editor()
+
+    # Open editor with validated command
+    try:
+        # Parse editor command (may include args like "code --wait")
+        editor_parts = shlex.split(editor_cmd)
+        subprocess.run([*editor_parts, str(config_path)], check=True)
+    except (subprocess.CalledProcessError, OSError, ValueError) as e:
+        raise RuntimeError(f"Editor failed: {e}") from e