Atheris fuzz

.github/workflows/pytest.yml → .github/workflows/lshell-tests.yml

@@ -1,7 +1,4 @@
-# This workflow will install Python dependencies, run tests and lint with a single version of Python
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
-
-name: Pytest
+name: Lshell Tests
 
 on:
   push:
@@ -12,8 +9,8 @@ permissions:
   contents: read
 
 jobs:
-  build:
-
+  pytest:
+    name: Pytest Unit/Integration Tests
     runs-on: ubuntu-latest
 
     steps:
@@ -27,31 +24,64 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install flake8 pytest
+        pip install pytest
         if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
     - name: Install the lshell package
       run: pip install .
-    - name: Lint with flake8
+    - name: Test with pytest
       run: |
+        pytest
+
+  lint:
+    name: Lint + Flake8
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10"]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Set up Python path
+      run: echo "PYTHONPATH=$PWD" >> $GITHUB_ENV
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pylint flake8
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+    - name: Analyse with pylint and flake8
+      run: |
+        pylint $(git ls-files '*.py')
         # stop the build if there are Python syntax errors or undefined names
         flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
         # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
         flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-    - name: Test with pytest
+
+  fuzz-security-parser:
+    name: Fuzz Security Parser/Policy
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install just
+      uses: taiki-e/install-action@just
+    - name: Fuzz security parser/policy
+      timeout-minutes: 45
       run: |
-        pytest
+        just test-fuzz-security-parser 20000
 
   ssh-e2e:
-    name: SSH E2E (Docker + Ansible)
+    name: SSH End-to-End (Docker + Ansible)
     runs-on: ubuntu-latest
 
     steps:
     - uses: actions/checkout@v4
-
     - name: Run SSH end-to-end tests
       run: |
         docker compose -f docker-compose.e2e.yml up --build --abort-on-container-exit --exit-code-from ansible-runner ansible-runner
-
     - name: Cleanup SSH E2E stack
       if: always()
       run: |

.gitignore

@@ -9,3 +9,4 @@ dist/
 test.lsh
 .pylint_cache/
 .pylint.d/
+.hypothesis/

Dockerfile

@@ -7,7 +7,7 @@ RUN \
     # For Debian/Ubuntu
     if [ -f /etc/debian_version ]; then \
         apt-get update && \
-        apt-get install -y python3 python3-pip git flake8 pylint python3-pytest python3-pexpect python3-setuptools python3-pyparsing vim procps sudo && \
+        apt-get install -y python3 python3-pip python3-dev build-essential clang libclang-rt-dev git flake8 pylint python3-pytest python3-pexpect python3-setuptools python3-pyparsing vim procps sudo && \
         apt-get clean; \
         groupadd -f testuser; \
         useradd -m -d /home/testuser -s /bin/bash -g testuser testuser; \
@@ -50,6 +50,11 @@ ENV PYTHONPATH=/home/testuser/lshell
 # Copy the code and requirements
 COPY . /home/testuser/lshell
 
+# Install test/runtime Python dependencies from the repository requirements.
+# Debian/Ubuntu images may require --break-system-packages (PEP 668).
+RUN python3 -m pip install --no-cache-dir -r /home/testuser/lshell/requirements.txt \
+    || python3 -m pip install --break-system-packages --no-cache-dir -r /home/testuser/lshell/requirements.txt
+
 # Install lshell from the source
 RUN python3 setup.py install
 

README.md

@@ -206,6 +206,21 @@ just sample-list
 just sample-ubuntu 01_baseline_allowlist.conf
 ```
 
+### Fuzzing parser/policy checks
+
+Run Atheris fuzzing in Debian Docker (dependencies installed in-container):
+
+```bash
+just test-fuzz-security-parser 20000
+```
+
+Optional local run (if you want to fuzz outside Docker):
+
+```bash
+pip install -r requirements-fuzz.txt
+python3 fuzz/fuzz_parser_policy.py -runs=20000
+```
+
 ## Contributing
 
 Open an issue or pull request: https://github.com/ghantoos/lshell/issues

fuzz/fuzz_parser_policy.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Atheris fuzz target for parser/policy security primitives."""
+
+import sys
+import tempfile
+
+try:
+    import atheris
+except ImportError as exc:  # pragma: no cover - optional dependency
+    raise SystemExit(
+        "atheris is not installed. Install fuzz deps with: pip install -r requirements-fuzz.txt"
+    ) from exc
+
+with atheris.instrument_imports():
+    from lshell import parser as lshell_parser
+    from lshell import policy
+    from lshell import sec
+    from lshell import utils
+
+
+class _NullLog:
+    """Minimal logger required by security helpers during fuzzing."""
+
+    def critical(self, _message):
+        """Discard critical log messages during fuzzing."""
+        return None
+
+    def error(self, _message):
+        """Discard error log messages during fuzzing."""
+        return None
+
+    def warning(self, _message):
+        """Discard warning log messages during fuzzing."""
+        return None
+
+    def info(self, _message):
+        """Discard info log messages during fuzzing."""
+        return None
+
+
+_FUZZ_TMP = tempfile.mkdtemp(prefix="lshell-fuzz-")
+_FUZZ_PARSER = lshell_parser.LshellParser()
+
+
+def _base_conf():
+    """Build an isolated, permissive config for parser/policy fuzz entrypoints."""
+    return {
+        "allowed": [
+            "echo",
+            "printf",
+            "cat",
+            "ls",
+            "pwd",
+            "true",
+            "false",
+            "cd",
+            "sudo",
+        ],
+        "allowed_file_extensions": [],
+        "forbidden": [";", "&", "|", "`", ">", "<", "$(", "${"],
+        "sudo_commands": ["ls"],
+        "overssh": ["ls", "pwd", "echo"],
+        "warning_counter": 64,
+        "path": ["/|", ""],
+        "home_path": _FUZZ_TMP,
+        "promptprint": "",
+        "logpath": _NullLog(),
+    }
+
+
+def _fuzz_one_line(line):
+    """Exercise parser and security check surfaces on one fuzzed command line."""
+    conf = _base_conf()
+    runtime_policy = {
+        "forbidden": conf["forbidden"],
+        "allowed": conf["allowed"],
+        "strict": 0,
+        "sudo_commands": conf["sudo_commands"],
+        "allowed_file_extensions": conf["allowed_file_extensions"],
+        "path": conf["path"],
+    }
+    try:
+        parsed = _FUZZ_PARSER.parse(line)
+        if parsed is not None:
+            _FUZZ_PARSER.validate_command(parsed)
+
+        utils.split_command_sequence(line)
+        utils.split_commands(line)
+        utils.expand_vars_quoted(line, support_advanced_braced=True)
+        utils.expand_vars_quoted(line, support_advanced_braced=False)
+        sec._path_tokens_from_line(line)
+        sec.check_forbidden_chars(line, conf, strict=0)
+        sec.check_path(line, conf, completion=1, strict=0)
+        sec.check_secure(line, conf, strict=0)
+        sec.check_allowed_file_extensions(line, [".txt", ".log"])
+        policy.policy_command_decision(line, runtime_policy)
+    except SystemExit:
+        # check_secure/check_path may terminate on warning exhaustion; ignore.
+        pass
+
+
+def test_one_input(data):
+    """Atheris entrypoint."""
+    line = data.decode("latin-1")
+    if not line:
+        return
+    _fuzz_one_line(line[:512])
+
+
+def main():
+    """Run Atheris fuzzing loop."""
+    atheris.Setup(sys.argv, test_one_input)
+    atheris.Fuzz()
+
+
+if __name__ == "__main__":
+    main()

justfile

@@ -188,6 +188,10 @@ test-lint-flake8:
     pylint $(git ls-files '*.py')
     flake8 lshell test
 
+# Run Atheris fuzzing in Debian Docker container (host deps not required)
+test-fuzz-security-parser runs='20000':
+    {{compose}} run --build --rm --entrypoint bash debian -lc "CLANG_BIN=clang python3 -m pip install --user --break-system-packages -r /app/requirements-fuzz.txt && PYTHONPATH=/app python3 /app/fuzz/fuzz_parser_policy.py -runs={{runs}}"
+
 # Full local validation in one command
 test-all:
     just test-lint-flake8
@@ -197,4 +201,5 @@ test-all:
       {{compose}} down -v --remove-orphans; \
       exit $rc\
     '
+    just test-fuzz-security-parser
     just test-ssh-e2e