test_entropy_detection.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# tests/tests_tools/test_entropy_detection.py
 
"""
Purpose
-------
FS-507 regression coverage for Shannon entropy-based secret detection.
 
Responsibilities
----------------
- Validate ``_shannon_entropy()`` for known inputs.
- Validate ``_check_entropy_violations()`` for AST-level detection.
- Validate that ``check_no_hardcoded_secrets()`` integrates entropy checking.
- Validate threshold configurability and the ``--no-entropy`` opt-out.
 
Diagnostics
-----------
Domain: SECRET-SCAN-TESTS
    Levels:
        L2 — test lifecycle
        L3 — assertion details
        L4 — deep tracing
 
Contracts
---------
- Tests operate on in-memory strings and AST snippets; no files are
  written.
"""
 
from __future__ import annotations
 
import ast
import json
import math
import textwrap
 
import pytest
 
from oct.tools.secret_scanner import (
    _shannon_entropy,
    _check_entropy_violations,
    _collect_docstring_node_ids,
    _collect_keyword_excluded_node_ids,
    _ENTROPY_DEFAULT_THRESHOLD,
    _DOCSTRING_ENTROPY_DEFAULT,
    _COMMENT_ENTROPY_DEFAULT,
    check_no_hardcoded_secrets,
)
 
 
# -------------------------------------------------------------------
# Shannon entropy unit tests
# -------------------------------------------------------------------
 
class TestShannonEntropy:
 
    def test_empty_string(self):
        assert _shannon_entropy("") == 0.0
 
    def test_single_repeated_char(self):
        assert _shannon_entropy("aaaa") == 0.0
        assert _shannon_entropy("bbbbbbbbb") == 0.0
 
    def test_two_equal_chars(self):
        result = _shannon_entropy("ab")
        assert abs(result - 1.0) < 1e-9
 
    def test_four_distinct_chars(self):
        result = _shannon_entropy("abcd")
        assert abs(result - 2.0) < 1e-9
 
    def test_high_entropy_base64(self):
        entropy = _shannon_entropy(_B64_TEST_STR)
        assert entropy > 4.0
        assert entropy == 5.0  # 32 unique chars → log2(32)
 
    def test_low_entropy_prose(self):
        prose = "the quick brown fox jumps"
        entropy = _shannon_entropy(prose)
        assert entropy < 4.5
 
    def test_entropy_increases_with_alphabet_size(self):
        small = _shannon_entropy("aabbccdd")
        large = _shannon_entropy("abcdefgh")
        assert large > small
 
 
# -------------------------------------------------------------------
# AST-level violation detection
# -------------------------------------------------------------------
 
class TestCheckEntropyViolations:
 
    def _parse(self, code: str) -> ast.Module:
        return ast.parse(textwrap.dedent(code))
 
    def test_high_entropy_string_detected(self):
        code = f'x = "{_B64_TEST_STR}"\n'
        tree = ast.parse(code)
        violations = _check_entropy_violations(tree, threshold=4.0)
        assert len(violations) == 1
        lineno, preview, entropy = violations[0]
        assert entropy == 5.0
 
    def test_short_strings_ignored(self):
        code = '''
        x = "short"
        '''
        tree = self._parse(code)
        violations = _check_entropy_violations(tree, threshold=1.0, min_length=16)
        assert len(violations) == 0
 
    def test_normal_string_passes(self):
        code = '''
        msg = "This is a normal message for the user interface"
        '''
        tree = self._parse(code)
        violations = _check_entropy_violations(tree, threshold=4.5)
        assert len(violations) == 0
 
    def test_threshold_configurable_strict(self):
        code = '''
        x = "abcdefghijklmnopqrstuvwxyz"
        '''
        tree = self._parse(code)
        low_threshold = _check_entropy_violations(tree, threshold=3.0)
        high_threshold = _check_entropy_violations(tree, threshold=7.0)
        assert len(low_threshold) >= len(high_threshold)
 
    def test_preview_truncated(self):
        long_str = "a" * 10 + "B" * 10 + "c" * 10 + "D" * 10
        code = f'x = "{long_str}"'
        tree = ast.parse(code)
        violations = _check_entropy_violations(tree, threshold=1.0, min_length=16)
        if violations:
            _, preview, _ = violations[0]
            assert len(preview) <= 27  # 24 + "..."
 
 
# -------------------------------------------------------------------
# Integration with check_no_hardcoded_secrets
# -------------------------------------------------------------------
 
class TestEntropyIntegration:
 
    def test_enabled_by_default(self):
        code = f'x = "{_B64_TEST_STR}"\n'
        passed, msg = check_no_hardcoded_secrets(code)
        assert not passed
        assert "high-entropy" in msg
 
    def test_disabled_with_zero_threshold(self):
        code = f'x = "{_B64_TEST_STR}"\n'
        passed, msg = check_no_hardcoded_secrets(code, code_entropy_threshold=0)
        assert passed
 
    def test_pattern_and_entropy_combine(self):
        code = f'api_key = "sk-{_B64_TEST_STR[:20]}"\n'
        passed, msg = check_no_hardcoded_secrets(code, code_entropy_threshold=4.0)
        assert not passed
        assert "api_key" in msg
        assert "high-entropy" in msg
 
    def test_json_output_includes_entropy(self, tmp_path, capsys):
        src = tmp_path / "test_project"
        src.mkdir()
        test_file = src / "example.py"
        test_file.write_text(textwrap.dedent(f'''\
        #!/usr/bin/env python3
        # -*- coding: utf-8 -*-
        # example.py
 
        x = "{_B64_TEST_STR}"
        '''), encoding="utf-8")
 
        from oct.linter.oct_lint import run_linter
        run_linter(src, ["--json", str(test_file)])
        captured = capsys.readouterr()
        data = json.loads(captured.out)
        file_result = data["files"][0]
        secrets_check = file_result["checks"]["no_hardcoded_secrets"]
        assert not secrets_check["pass"]
        assert "high-entropy" in secrets_check["message"]
 
    def test_default_threshold_value(self):
        assert _ENTROPY_DEFAULT_THRESHOLD == 4.5
 
    def test_custom_threshold_via_param(self):
        code = textwrap.dedent('''\
        x = "abcdefghijklmnop"
        ''')
        entropy_val = _shannon_entropy("abcdefghijklmnop")
        strict = check_no_hardcoded_secrets(code, code_entropy_threshold=entropy_val - 0.1)
        lenient = check_no_hardcoded_secrets(code, code_entropy_threshold=entropy_val + 0.5)
        assert not strict[0]
        assert lenient[0]
 
 
# -------------------------------------------------------------------
# Per-context entropy thresholds (docstring vs code string)
# -------------------------------------------------------------------
 
# 32 unique chars → entropy = 5.0 bits/char (test fixture for base64-like strings)
_B64_TEST_STR = "aB3dE7fG9hJ2kL5mN8pQ1rS4tU6vW0xY"
# 28 unique chars → entropy ≈ 4.807 bits/char (above 4.5, below 5.0)
_MID_ENTROPY_STR = "abcdefghijklmnopqrstuvwxyz01"
# 38 unique chars → entropy ≈ 5.248 bits/char (above 5.0)
_HIGH_ENTROPY_STR = "abcdefghijklmnopqrstuvwxyz0123456789AB"
 
 
class TestDocstringThresholds:
    """Context-aware entropy scanning: docstrings use strict >, code uses >=."""
 
    def _parse(self, code: str) -> ast.Module:
        return ast.parse(textwrap.dedent(code))
 
    def test_docstring_uses_higher_threshold(self):
        """Module docstring at ~4.8 bits/char passes default 5.0 threshold."""
        code = f'"""{_MID_ENTROPY_STR}"""\nx = 1\n'
        tree = ast.parse(code)
        violations = _check_entropy_violations(tree, threshold=4.5, docstring_threshold=5.0)
        assert len(violations) == 0
 
    def test_docstring_caught_above_docstring_threshold(self):
        """Module docstring at ~5.2 bits/char is caught (strict >)."""
        code = f'"""{_HIGH_ENTROPY_STR}"""\nx = 1\n'
        tree = ast.parse(code)
        violations = _check_entropy_violations(tree, threshold=4.5, docstring_threshold=5.0)
        assert len(violations) == 1
 
    def test_function_docstring_uses_higher_threshold(self):
        """Function docstring at ~4.8 bits/char passes default 5.0 threshold."""
        code = textwrap.dedent(f'''\
        def example():
            """{_MID_ENTROPY_STR}"""
            return 42
        ''')
        tree = ast.parse(code)
        violations = _check_entropy_violations(tree, threshold=4.5, docstring_threshold=5.0)
        assert len(violations) == 0
 
    def test_class_docstring_uses_higher_threshold(self):
        """Class docstring at ~4.8 bits/char passes default 5.0 threshold."""
        code = textwrap.dedent(f'''\
        class Example:
            """{_MID_ENTROPY_STR}"""
            pass
        ''')
        tree = ast.parse(code)
        violations = _check_entropy_violations(tree, threshold=4.5, docstring_threshold=5.0)
        assert len(violations) == 0
 
    def test_non_docstring_uses_normal_threshold(self):
        """Regular string at ~4.8 bits/char IS caught at code threshold 4.5."""
        code = f'x = "{_MID_ENTROPY_STR}"\n'
        tree = ast.parse(code)
        violations = _check_entropy_violations(tree, threshold=4.5, docstring_threshold=5.0)
        assert len(violations) == 1
 
    def test_custom_docstring_threshold_from_parameter(self):
        """Explicit docstring_entropy_threshold=4.0 catches docstrings above 4.0."""
        code = f'"""{_MID_ENTROPY_STR}"""\nx = 1\n'
        tree = ast.parse(code)
        # ~4.8 exceeds strict > 4.0
        violations = _check_entropy_violations(tree, threshold=4.5, docstring_threshold=4.0)
        assert len(violations) == 1
 
    def test_code_string_at_exact_threshold_is_caught(self):
        """Code string at exactly its threshold IS caught (>= semantics)."""
        test_str = _MID_ENTROPY_STR
        exact_entropy = _shannon_entropy(test_str)
        code = f'x = "{test_str}"\n'
        tree = ast.parse(code)
        # Set threshold to exact entropy — >= should catch it
        violations = _check_entropy_violations(tree, threshold=exact_entropy, docstring_threshold=9.0)
        assert len(violations) == 1
 
    def test_docstring_at_exact_threshold_passes(self):
        """Docstring at exactly its threshold is NOT caught (strict > semantics)."""
        test_str = _MID_ENTROPY_STR
        exact_entropy = _shannon_entropy(test_str)
        code = f'"""{test_str}"""\nx = 1\n'
        tree = ast.parse(code)
        # Set docstring_threshold to exact entropy — strict > should NOT catch it
        violations = _check_entropy_violations(tree, threshold=4.5, docstring_threshold=exact_entropy)
        assert len(violations) == 0
 
    def test_comment_threshold_accepted_but_unused(self):
        """comment_threshold parameter is accepted without error."""
        code = f'x = "{_MID_ENTROPY_STR}"\n'
        tree = ast.parse(code)
        # Should not raise, and should still catch the code string
        violations = _check_entropy_violations(
            tree, threshold=4.5, docstring_threshold=5.0, comment_threshold=3.0,
        )
        assert len(violations) == 1
 
 
# -------------------------------------------------------------------
# OI-540: Field-name exclusions (keyword arguments in Call nodes)
# -------------------------------------------------------------------
 
class TestFieldNameExclusions:
 
    def test_keyword_excluded_skips_matching(self):
        """Keyword arg matching a field pattern is excluded from entropy."""
        code = f'RuleInfo(correct_pattern="{_B64_TEST_STR}")\n'
        tree = ast.parse(code)
        excluded = _collect_keyword_excluded_node_ids(tree, ["correct_pattern"])
        violations = _check_entropy_violations(
            tree, threshold=4.0, excluded_node_ids=frozenset(excluded),
        )
        assert len(violations) == 0
 
    def test_keyword_excluded_does_not_skip_unmatched(self):
        """Keyword arg NOT in patterns is still flagged."""
        code = f'RuleInfo(name="{_B64_TEST_STR}")\n'
        tree = ast.parse(code)
        excluded = _collect_keyword_excluded_node_ids(tree, ["correct_pattern"])
        violations = _check_entropy_violations(
            tree, threshold=4.0, excluded_node_ids=frozenset(excluded),
        )
        assert len(violations) == 1
 
    def test_keyword_exclusion_only_affects_call_kwargs(self):
        """Regular assignment to excluded name IS still flagged."""
        code = f'correct_pattern = "{_B64_TEST_STR}"\n'
        tree = ast.parse(code)
        excluded = _collect_keyword_excluded_node_ids(tree, ["correct_pattern"])
        violations = _check_entropy_violations(
            tree, threshold=4.0, excluded_node_ids=frozenset(excluded),
        )
        assert len(violations) == 1
 
    def test_empty_patterns_returns_empty(self):
        """Empty pattern list produces empty excluded set."""
        code = f'RuleInfo(correct_pattern="{_B64_TEST_STR}")\n'
        tree = ast.parse(code)
        excluded = _collect_keyword_excluded_node_ids(tree, [])
        assert len(excluded) == 0
 
    def test_integration_excluded_field_patterns(self):
        """check_no_hardcoded_secrets respects excluded_field_patterns."""
        code = f'RuleInfo(correct_pattern="{_B64_TEST_STR}")\n'
        passed, msg = check_no_hardcoded_secrets(
            code, excluded_field_patterns=["correct_pattern"],
        )
        assert passed
 
    def test_integration_without_exclusion_still_flags(self):
        """Without excluded_field_patterns the same code is flagged."""
        code = f'RuleInfo(correct_pattern="{_B64_TEST_STR}")\n'
        passed, msg = check_no_hardcoded_secrets(code)
        assert not passed
        assert "high-entropy" in msg
 
 
# -------------------------------------------------------------------
# OI-540: octrc validation for entropy_exclusions
# -------------------------------------------------------------------
 
class TestExclusionValidation:
 
    def test_valid_exclusions_pass(self):
        """Well-formed entropy_exclusions pass validation."""
        from oct.linter.oct_lint import _validate_octrc_schema
        cfg = {
            "secret_scanner": {
                "entropy_exclusions": [
                    {
                        "field_name_pattern": "correct_pattern",
                        "context": "namedtuple_field",
                    },
                    {
                        "path_pattern": "tests/",
                        "context": "test_directory",
                        "restrictions": {"exempt_entropy_only": True},
                    },
                ]
            }
        }
        errors = _validate_octrc_schema(cfg)
        assert len(errors) == 0
 
    def test_bad_context_value(self):
        """Invalid context value is caught."""
        from oct.linter.oct_lint import _validate_octrc_schema
        cfg = {
            "secret_scanner": {
                "entropy_exclusions": [
                    {"context": "unknown_type", "field_name_pattern": "x"},
                ]
            }
        }
        errors = _validate_octrc_schema(cfg)
        assert any("context" in e for e in errors)
 
    def test_missing_field_name_pattern(self):
        """namedtuple_field without field_name_pattern is caught."""
        from oct.linter.oct_lint import _validate_octrc_schema
        cfg = {
            "secret_scanner": {
                "entropy_exclusions": [
                    {"context": "namedtuple_field"},
                ]
            }
        }
        errors = _validate_octrc_schema(cfg)
        assert any("field_name_pattern" in e for e in errors)
 
    def test_missing_path_pattern(self):
        """test_directory without path_pattern is caught."""
        from oct.linter.oct_lint import _validate_octrc_schema
        cfg = {
            "secret_scanner": {
                "entropy_exclusions": [
                    {"context": "test_directory"},
                ]
            }
        }
        errors = _validate_octrc_schema(cfg)
        assert any("path_pattern" in e for e in errors)
 
    def test_exclusions_not_array(self):
        """entropy_exclusions must be an array."""
        from oct.linter.oct_lint import _validate_octrc_schema
        cfg = {
            "secret_scanner": {
                "entropy_exclusions": "not_a_list",
            }
        }
        errors = _validate_octrc_schema(cfg)
        assert any("must be an array" in e for e in errors)
 
 
# -------------------------------------------------------------------
# OI-540: Shared waiver module
# -------------------------------------------------------------------
 
class TestWaiverModule:
 
    def test_import_from_shared_module(self):
        """parse_inline_waivers is importable from oct.core.waivers."""
        from oct.core.waivers import parse_inline_waivers as fn
        assert callable(fn)
 
    def test_basic_waiver_parsing(self):
        """Shared parse_inline_waivers returns correct structure."""
        from oct.core.waivers import parse_inline_waivers
        text = 'x = 1  # OCT-LINT: disable=no_hardcoded_secrets reason="test fixture"'
        waivers = parse_inline_waivers(text)
        assert 1 in waivers
        assert waivers[1]["rule"] == "no_hardcoded_secrets"
        assert waivers[1]["reason"] is not None