devshield-scanner 0.1.1__tar.gz → 0.2.0__tar.gz

{devshield_scanner-0.1.1 → devshield_scanner-0.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: devshield-scanner
-Version: 0.1.1
-Summary: Read-only Linux host and Docker filesystem inspection using ClamAV
+Version: 0.2.0
+Summary: Linux host/Docker inspection with opt-in response for detected process executables
 License-Expression: MIT
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
@@ -14,6 +14,14 @@ Dynamic: license-file
 
 # DevShield for Linux
 
+## Process-first response (0.2.0)
+
+`sudo /opt/devshield/bin/devshield --remediate-running` first snapshots and scans running executables, sends SIGKILL to signature-detected processes, and attempts to move matching host executables into `/var/lib/devshield/quarantine`. It then scans host files and Docker data. Without this flag, scanning remains read-only. This is an experimental opt-in response mode and can interrupt production services. Process response currently requires root and Python/Linux pidfd support (normally Python 3.9+ and Linux 5.3+).
+
+Heuristic, PUA, encrypted-content, scan-limit and EICAR test alerts never trigger automatic process response. Evidence copies and action records are saved before termination. PID 1, DevShield and its ancestors are excluded. Original-file moves require a matching inode and a same-filesystem rename; failures are reported rather than falling back to destructive copy/delete. Container executables are not moved: rebuild affected containers from trusted images. Supervisors may restart terminated processes. Script interpreters, injected code, memory-only malware and persistence are not comprehensively inspected, and files found during the subsequent host/container scan are not automatically removed. Quarantine samples must not be executed. Quarantine is excluded from later scans.
+
+`--max-files 200000` raises the archive member-count limit when needed. Example for the large container export discussed during validation: `devshield --remediate-running --max-files 200000 --max-filesize-mb 1536 --max-scansize-mb 2048`. Limits do not apply to process snapshots, which retain ClamAV defaults with limit alerts. Increasing limits raises resource use. A privileged attacker can still evade or interfere with live-host inspection. There is no guarantee of complete malware removal.
+
 An installable Python CLI package is included. The Python distribution is `devshield-scanner`; the command is `devshield`. See **INSTALL.md** for isolated installation under `/opt/devshield`. `devshield --version` displays the CLI version.
 
 Version 0.1.1 enables ClamAV scan-limit alerts and marks zero-data scans, missing summaries and logged warnings/errors as incomplete coverage (exit 2), even when ClamAV returns 0. Limit alerts are not proof of malware. Optional `--max-filesize-mb` and `--max-scansize-mb` override engine limits in MB. Increasing limits can increase memory, CPU and runtime; engine hard limits still apply. A positive data count alone does not prove every archive entry was inspected.

devshield_scanner-0.1.1/devshield_scanner.egg-info/PKG-INFO → devshield_scanner-0.2.0/README.md

@@ -1,59 +1,53 @@
-Metadata-Version: 2.4
-Name: devshield-scanner
-Version: 0.1.1
-Summary: Read-only Linux host and Docker filesystem inspection using ClamAV
-License-Expression: MIT
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
-# DevShield for Linux
-
-An installable Python CLI package is included. The Python distribution is `devshield-scanner`; the command is `devshield`. See **INSTALL.md** for isolated installation under `/opt/devshield`. `devshield --version` displays the CLI version.
-
-Version 0.1.1 enables ClamAV scan-limit alerts and marks zero-data scans, missing summaries and logged warnings/errors as incomplete coverage (exit 2), even when ClamAV returns 0. Limit alerts are not proof of malware. Optional `--max-filesize-mb` and `--max-scansize-mb` override engine limits in MB. Increasing limits can increase memory, CPU and runtime; engine hard limits still apply. A positive data count alone does not prove every archive entry was inspected.
-
-Read-only host and Docker filesystem malware scanning using the locally installed ClamAV signature engine. Requires Linux, Python 3.8+, `clamscan`, updated ClamAV databases, and the Docker CLI for container scanning. Run on the Docker host with a local Unix socket context. Root access normally provides the required file/socket access.
-
-On Debian/Ubuntu, install prerequisites using your normal package-management policy:
-
-```sh
-sudo apt-get update
-sudo apt-get install python3 clamav clamav-freshclam
-```
-
-Ensure the ClamAV databases have downloaded before scanning. Use your distribution's freshclam service, or `sudo freshclam` if that service is not already managing updates. The scanner does not install software, change services, or update databases automatically. Docker must already be installed if you use it.
-
-Copy this folder onto the server, then run:
-
-```sh
-sudo python3 devshield_linux.py
-```
-
-Console messages identify each stage and show a heartbeat every 10 seconds during long scans. Verbose file-level progress is saved to each stage's log; inspect a log with `tail -f /path/printed/by/script.log`. JSON results are checkpointed after every completed scan and on interruption, under `/var/log/devshield/<run>/report.json`.
-
-```sh
-# Check a small directory first
-sudo python3 devshield_linux.py --host-root /srv/project --skip-docker
-
-# Containers and volumes only
-sudo python3 devshield_linux.py --skip-host
-
-# Use a scratch disk with room for the largest container filesystem export
-sudo python3 devshield_linux.py --temp-dir /mnt/scratch --heartbeat 5
-```
-
-Host scanning starts at `/` and traverses mounted filesystems, including potentially slow network mounts. `/proc`, `/sys`, `/dev`, `/run`, raw default Docker/containerd storage, the report directory and scratch directory are excluded. No symlinks are followed. Custom Docker storage may be scanned twice. Logs can be large and contain private file paths; keep them private.
-
-For each running container the script uses `docker export`, scans the resulting TAR as an archive, then deletes only its own temporary export. It does not execute programs inside containers, extract archives, stop containers or change their files. It separately scans bind-mount sources and discovered Docker volumes, including unused volumes. Remote daemons are rejected. Volume plugins/network-backed volumes may need separate mounting and scanning. If using a local socket proxy to a remote daemon, do not use this script: mount paths must refer to this machine.
-
-Stopped containers, unused image layers, RAM, kernel state and rootkits are not covered. ClamAV's configured/default size, archive and recursion limits still apply, including to large container TAR exports; a successful scan can miss content past those limits. Review ClamAV summaries and warnings in every log. This is a best-effort filesystem scan, not a comprehensive compromise assessment. Live files can change during scanning. Use a trusted rescue environment for suspected root-level compromise.
-
-Exit status: 0 = no signature detections reported and no recorded orchestration errors; 1 = detections; 2 = incomplete/error (detections may also exist; always inspect the report). No deletion or quarantine is requested. Reports persist if Docker scanning fails or the scan is interrupted with Ctrl+C. A forced kill or power loss may lose the active stage, but earlier checkpoints remain.
-
-Validation on the development Windows machine covers syntax and mocked orchestration only. A real Linux/Docker/ClamAV integration scan must be validated on your server before operational use.
+# DevShield for Linux
+
+## Process-first response (0.2.0)
+
+`sudo /opt/devshield/bin/devshield --remediate-running` first snapshots and scans running executables, sends SIGKILL to signature-detected processes, and attempts to move matching host executables into `/var/lib/devshield/quarantine`. It then scans host files and Docker data. Without this flag, scanning remains read-only. This is an experimental opt-in response mode and can interrupt production services. Process response currently requires root and Python/Linux pidfd support (normally Python 3.9+ and Linux 5.3+).
+
+Heuristic, PUA, encrypted-content, scan-limit and EICAR test alerts never trigger automatic process response. Evidence copies and action records are saved before termination. PID 1, DevShield and its ancestors are excluded. Original-file moves require a matching inode and a same-filesystem rename; failures are reported rather than falling back to destructive copy/delete. Container executables are not moved: rebuild affected containers from trusted images. Supervisors may restart terminated processes. Script interpreters, injected code, memory-only malware and persistence are not comprehensively inspected, and files found during the subsequent host/container scan are not automatically removed. Quarantine samples must not be executed. Quarantine is excluded from later scans.
+
+`--max-files 200000` raises the archive member-count limit when needed. Example for the large container export discussed during validation: `devshield --remediate-running --max-files 200000 --max-filesize-mb 1536 --max-scansize-mb 2048`. Limits do not apply to process snapshots, which retain ClamAV defaults with limit alerts. Increasing limits raises resource use. A privileged attacker can still evade or interfere with live-host inspection. There is no guarantee of complete malware removal.
+
+An installable Python CLI package is included. The Python distribution is `devshield-scanner`; the command is `devshield`. See **INSTALL.md** for isolated installation under `/opt/devshield`. `devshield --version` displays the CLI version.
+
+Version 0.1.1 enables ClamAV scan-limit alerts and marks zero-data scans, missing summaries and logged warnings/errors as incomplete coverage (exit 2), even when ClamAV returns 0. Limit alerts are not proof of malware. Optional `--max-filesize-mb` and `--max-scansize-mb` override engine limits in MB. Increasing limits can increase memory, CPU and runtime; engine hard limits still apply. A positive data count alone does not prove every archive entry was inspected.
+
+Read-only host and Docker filesystem malware scanning using the locally installed ClamAV signature engine. Requires Linux, Python 3.8+, `clamscan`, updated ClamAV databases, and the Docker CLI for container scanning. Run on the Docker host with a local Unix socket context. Root access normally provides the required file/socket access.
+
+On Debian/Ubuntu, install prerequisites using your normal package-management policy:
+
+```sh
+sudo apt-get update
+sudo apt-get install python3 clamav clamav-freshclam
+```
+
+Ensure the ClamAV databases have downloaded before scanning. Use your distribution's freshclam service, or `sudo freshclam` if that service is not already managing updates. The scanner does not install software, change services, or update databases automatically. Docker must already be installed if you use it.
+
+Copy this folder onto the server, then run:
+
+```sh
+sudo python3 devshield_linux.py
+```
+
+Console messages identify each stage and show a heartbeat every 10 seconds during long scans. Verbose file-level progress is saved to each stage's log; inspect a log with `tail -f /path/printed/by/script.log`. JSON results are checkpointed after every completed scan and on interruption, under `/var/log/devshield/<run>/report.json`.
+
+```sh
+# Check a small directory first
+sudo python3 devshield_linux.py --host-root /srv/project --skip-docker
+
+# Containers and volumes only
+sudo python3 devshield_linux.py --skip-host
+
+# Use a scratch disk with room for the largest container filesystem export
+sudo python3 devshield_linux.py --temp-dir /mnt/scratch --heartbeat 5
+```
+
+Host scanning starts at `/` and traverses mounted filesystems, including potentially slow network mounts. `/proc`, `/sys`, `/dev`, `/run`, raw default Docker/containerd storage, the report directory and scratch directory are excluded. No symlinks are followed. Custom Docker storage may be scanned twice. Logs can be large and contain private file paths; keep them private.
+
+For each running container the script uses `docker export`, scans the resulting TAR as an archive, then deletes only its own temporary export. It does not execute programs inside containers, extract archives, stop containers or change their files. It separately scans bind-mount sources and discovered Docker volumes, including unused volumes. Remote daemons are rejected. Volume plugins/network-backed volumes may need separate mounting and scanning. If using a local socket proxy to a remote daemon, do not use this script: mount paths must refer to this machine.
+
+Stopped containers, unused image layers, RAM, kernel state and rootkits are not covered. ClamAV's configured/default size, archive and recursion limits still apply, including to large container TAR exports; a successful scan can miss content past those limits. Review ClamAV summaries and warnings in every log. This is a best-effort filesystem scan, not a comprehensive compromise assessment. Live files can change during scanning. Use a trusted rescue environment for suspected root-level compromise.
+
+Exit status: 0 = no signature detections reported and no recorded orchestration errors; 1 = detections; 2 = incomplete/error (detections may also exist; always inspect the report). No deletion or quarantine is requested. Reports persist if Docker scanning fails or the scan is interrupted with Ctrl+C. A forced kill or power loss may lose the active stage, but earlier checkpoints remain.
+
+Validation on the development Windows machine covers syntax and mocked orchestration only. A real Linux/Docker/ClamAV integration scan must be validated on your server before operational use.

{devshield_scanner-0.1.1 → devshield_scanner-0.2.0}/devshield_linux.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Read-only Linux host/Docker filesystem scan using the installed ClamAV engine."""
+"""Linux host/Docker inspection with opt-in response for detected running executables."""
 import argparse
 import contextlib
 import datetime as dt
@@ -12,6 +12,7 @@ import subprocess
 import sys
 import tempfile
 import time
+from devshield_processes import inspect_running
 
 
 def coverage_warnings(log_path):
@@ -35,7 +36,10 @@ def coverage_warnings(log_path):
 
 def main():
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument('--version', action='version', version='DevShield 0.1.1')
+    parser.add_argument('--version', action='version', version='DevShield 0.2.0')
+    parser.add_argument('--remediate-running', action='store_true', help='FIRST scan process executables; kill signature-detected processes and quarantine host binaries. Can interrupt services.')
+    parser.add_argument('--quarantine', default='/var/lib/devshield/quarantine', help='Root-owned 0700 quarantine directory')
+    parser.add_argument('--max-files', type=int, help='ClamAV maximum archive member count')
     parser.add_argument('--max-filesize-mb', type=int, help='ClamAV per-file limit in MB (default: engine setting)')
     parser.add_argument('--max-scansize-mb', type=int, help='ClamAV archive scan limit in MB (default: engine setting)')
     parser.add_argument('--host-root', default='/', help='Host directory to scan (default /)')
@@ -49,9 +53,9 @@ def main():
         parser.error('Run this script on Linux.')
     if args.heartbeat < 1:
         parser.error('--heartbeat must be positive')
-    for value in (args.max_filesize_mb, args.max_scansize_mb):
+    for value in (args.max_filesize_mb, args.max_scansize_mb, args.max_files):
         if value is not None and value < 1:
-            parser.error('Scan size limits must be positive MB values')
+            parser.error('Scan limits must be positive')
     if not shutil.which('clamscan'):
         parser.error('clamscan is missing. Install ClamAV and update its databases first; see README.md.')
     report_dir = Path(args.reports).resolve() / (dt.datetime.now(dt.timezone.utc).strftime('%Y%m%dT%H%M%SZ') + '-' + str(os.getpid()))
@@ -110,6 +114,8 @@ def main():
             command.append(f'--max-filesize={args.max_filesize_mb}M')
         if args.max_scansize_mb is not None:
             command.append(f'--max-scansize={args.max_scansize_mb}M')
+        if args.max_files is not None:
+            command.append(f'--max-files={args.max_files}')
         command.extend('--exclude-dir=^' + re.escape(str(Path(p).resolve())) + r'(/|$)' for p in excludes)
         rc, log = run([*command, '--', str(path)], label)
         warnings = coverage_warnings(log)
@@ -129,12 +135,14 @@ def main():
         version = subprocess.run(['clamscan', '--version'], capture_output=True, text=True)
         report['engine'] = version.stdout.strip()
         save()
+        if args.remediate_running:
+            inspect_running(run, issue, save, report, scratch.name, args.quarantine, coverage_warnings)
         if not args.skip_host:
             if not Path(args.host_root).is_dir():
                 issue('Host root is not a directory: ' + args.host_root)
             else:
                 scan(Path(args.host_root).resolve(), 'Host filesystem',
-                     ['/proc', '/sys', '/dev', '/run', '/var/lib/docker', '/var/lib/containerd', report_dir.parent, scratch.name])
+                     ['/proc', '/sys', '/dev', '/run', '/var/lib/docker', '/var/lib/containerd', report_dir.parent, scratch.name, args.quarantine])
         if not args.skip_docker:
             if not shutil.which('docker'):
                 issue('Docker CLI missing; containers and volumes were not inspected.')
@@ -176,7 +184,7 @@ def main():
                             issue(f'Volume {name}: {exc}')
                     for source in sorted(mounts):
                         if Path(source).exists():
-                            scan(source, 'Docker mount ' + source, ['/proc', '/sys', '/dev', '/run', report_dir.parent, scratch.name])
+                            scan(source, 'Docker mount ' + source, ['/proc', '/sys', '/dev', '/run', report_dir.parent, scratch.name, args.quarantine])
                         else:
                             issue('Docker mount source inaccessible: ' + source)
                 except (OSError, RuntimeError, ValueError, KeyError, subprocess.SubprocessError) as exc:
@@ -192,7 +200,7 @@ def main():
         print(f'Report: {report_dir / "report.json"}', flush=True)
     if report['issues']:
         return 2
-    return 1 if any(s['exit_code'] == 1 for s in report['scans']) else 0
+    return 1 if report.get('process_response') or any(s['exit_code'] == 1 for s in report['scans']) else 0
 
 
 if __name__ == '__main__':

devshield_scanner-0.2.0/devshield_processes.py

@@ -0,0 +1,169 @@
+"""Conservative process-executable response; never infer a verdict from a PID/name."""
+import hashlib
+import os
+from pathlib import Path
+import re
+import signal
+import stat
+
+
+def signature_names(log_path):
+    names = []
+    with open(log_path, encoding='utf-8', errors='replace') as stream:
+        for line in stream:
+            match = re.search(r': ([^\r\n]+) FOUND\s*$', line)
+            if match:
+                name = match.group(1)
+                # Coverage, heuristic/PUA and test alerts are insufficient for automatic response.
+                if not name.startswith(('Heuristics.', 'PUA.')) and not re.search(r'eicar|test[.-]signature', name, re.I):
+                    names.append(name)
+    return names
+
+
+def digest(stream):
+    stream.seek(0)
+    result = hashlib.sha256()
+    for block in iter(lambda: stream.read(1024 * 1024), b''):
+        result.update(block)
+    return result.hexdigest()
+
+
+def protected_pids():
+    protected = {1}
+    pid = os.getpid()
+    while pid > 0 and pid not in protected:
+        protected.add(pid)
+        try:
+            text = Path(f'/proc/{pid}/stat').read_text()
+            pid = int(text[text.rfind(')') + 2:].split()[1])
+        except (OSError, ValueError, IndexError):
+            break
+    return protected
+
+
+def move_original(source, before, destination):
+    """Same-filesystem rename only; never copy-and-delete across devices."""
+    parentfd = os.open(source.parent, os.O_RDONLY | os.O_DIRECTORY)
+    try:
+        current = os.stat(source.name, dir_fd=parentfd, follow_symlinks=False)
+        if not stat.S_ISREG(current.st_mode) or (current.st_dev, current.st_ino) != (before.st_dev, before.st_ino):
+            raise RuntimeError('Original path changed; not moved')
+        if destination.exists():
+            raise RuntimeError('Original quarantine destination already exists')
+        os.rename(source.name, str(destination), src_dir_fd=parentfd)
+        os.chmod(destination, 0o600)
+    finally:
+        os.close(parentfd)
+
+
+def inspect_running(run, issue, save, report, scratch, quarantine, coverage_warnings):
+    """Scan immutable copies, pin process identities, preserve evidence before SIGKILL."""
+    if os.geteuid() != 0:
+        issue('Running-process response requires root; stage skipped.')
+        return
+    if not hasattr(os, 'pidfd_open') or not hasattr(signal, 'pidfd_send_signal'):
+        issue('Running-process response requires Python/Linux pidfd support; no unsafe PID-only fallback is used.')
+        return
+    quarantine = Path(quarantine).absolute()
+    quarantine.mkdir(parents=True, mode=0o700, exist_ok=True)
+    metadata = quarantine.lstat()
+    if not stat.S_ISDIR(metadata.st_mode) or metadata.st_uid != 0 or metadata.st_mode & 0o077:
+        issue('Quarantine must be a root-owned directory with mode 0700; stage skipped.')
+        return
+    protected = protected_pids()
+    results = report.setdefault('process_response', [])
+    cache = {}
+    host_namespace = os.readlink('/proc/self/ns/mnt')
+    pids = sorted(int(p.name) for p in Path('/proc').iterdir() if p.name.isdigit())
+    print(f'[Processes] Inspecting executables for {len(pids)} processes. Scripts, RAM and persistence are not covered.', flush=True)
+    for number, pid in enumerate(pids, 1):
+        if pid in protected:
+            continue
+        pidfd = None
+        try:
+            pidfd = os.pidfd_open(pid)
+            exe_link = Path(f'/proc/{pid}/exe')
+            with exe_link.open('rb') as executable:
+                before = os.fstat(executable.fileno())
+                if not stat.S_ISREG(before.st_mode):
+                    continue
+                key = (before.st_dev, before.st_ino, before.st_size, before.st_mtime_ns, before.st_ctime_ns)
+                source_name = os.readlink(exe_link)
+                print(f'[Processes {number}/{len(pids)}] PID {pid}: {source_name}', flush=True)
+                if key not in cache:
+                    snapshot = Path(scratch) / f'process-{pid}.bin'
+                    with snapshot.open('xb') as target:
+                        for block in iter(lambda: executable.read(1024 * 1024), b''):
+                            target.write(block)
+                    with snapshot.open('rb') as target:
+                        snapshot_hash = digest(target)
+                    rc, log = run(['clamscan', '--infected', '--alert-exceeds-max=yes', '--', str(snapshot)], f'Process executable PID {pid}')
+                    for warning in coverage_warnings(log):
+                        issue(f'PID {pid}: {warning} See {log}')
+                    names = signature_names(log) if rc == 1 else []
+                    # Never kill when the executable changed while its snapshot was scanned.
+                    if digest(executable) != snapshot_hash:
+                        issue(f'PID {pid}: executable changed during inspection; response skipped.')
+                        snapshot.unlink()
+                        continue
+                    if rc not in (0, 1):
+                        issue(f'PID {pid}: executable scan failed; see {log}')
+                    if rc == 1 and not names:
+                        issue(f'PID {pid}: non-actionable alert; no process killed; see {log}')
+                    if names:
+                        evidence = quarantine / (snapshot_hash + '.sample')
+                        # Create-only: never overwrite a prior sample or follow a pre-existing symlink.
+                        try:
+                            with evidence.open('xb') as target, snapshot.open('rb') as original:
+                                os.chmod(evidence, 0o600)
+                                for block in iter(lambda: original.read(1024 * 1024), b''):
+                                    target.write(block)
+                        except FileExistsError:
+                            if evidence.is_symlink():
+                                raise RuntimeError('Unsafe quarantine sample link')
+                            with evidence.open('rb') as existing:
+                                if digest(existing) != snapshot_hash:
+                                    raise RuntimeError('Quarantine sample hash mismatch')
+                        cache[key] = (names, snapshot_hash, log, str(evidence))
+                    else:
+                        cache[key] = ([], snapshot_hash, log, None)
+                    snapshot.unlink()
+                names, snapshot_hash, log, evidence = cache[key]
+                if not names:
+                    continue
+                current = exe_link.stat()
+                if (current.st_dev, current.st_ino) != (before.st_dev, before.st_ino) or digest(executable) != snapshot_hash:
+                    issue(f'PID {pid}: executable identity changed; response skipped.')
+                    continue
+                action = {'pid': pid, 'executable': source_name, 'signatures': names, 'sha256': snapshot_hash,
+                          'log': log, 'evidence': evidence, 'termination': 'pending', 'file_action': 'not moved'}
+                results.append(action)
+                container_namespace = os.readlink(f'/proc/{pid}/ns/mnt') != host_namespace
+                save()  # Preserve evidence and intent before touching the process.
+                signal.pidfd_send_signal(pidfd, signal.SIGKILL)
+                action['termination'] = 'SIGKILL sent via pidfd'
+                print(f'[RESPONSE] PID {pid}: SIGKILL sent; signatures: {names}', flush=True)
+                save()
+                # Never resolve a container path against the host filesystem.
+                if container_namespace:
+                    action['file_action'] = 'container namespace: evidence saved, original not moved; rebuild container'
+                    issue(f'PID {pid}: container executable requires container rebuild; supervisors may restart it.')
+                elif source_name.endswith(' (deleted)'):
+                    action['file_action'] = 'original already unlinked; evidence retained'
+                else:
+                    source = Path(source_name)
+                    # Pin the parent directory to avoid a changed parent/symlink redirect.
+                    destination = quarantine / f'{snapshot_hash}-{pid}.original'
+                    move_original(source, before, destination)
+                    action['file_action'] = 'moved to ' + str(destination)
+                save()
+        except (FileNotFoundError, ProcessLookupError):
+            # Most often a process exited between enumeration and inspection.
+            if 'action' in locals() and action.get('pid') == pid:
+                action['file_action'] = 'process/path exited during response; inspect source manually'
+                issue(f'PID {pid}: process/path disappeared during response; original removal unverified.')
+        except (OSError, RuntimeError) as exc:
+            issue(f'PID {pid}: {exc}; consult process_response for actions already performed.')
+        finally:
+            if pidfd is not None:
+                os.close(pidfd)

devshield_scanner-0.1.1/README.md → devshield_scanner-0.2.0/devshield_scanner.egg-info/PKG-INFO

@@ -1,45 +1,67 @@
-# DevShield for Linux
-
-An installable Python CLI package is included. The Python distribution is `devshield-scanner`; the command is `devshield`. See **INSTALL.md** for isolated installation under `/opt/devshield`. `devshield --version` displays the CLI version.
-
-Version 0.1.1 enables ClamAV scan-limit alerts and marks zero-data scans, missing summaries and logged warnings/errors as incomplete coverage (exit 2), even when ClamAV returns 0. Limit alerts are not proof of malware. Optional `--max-filesize-mb` and `--max-scansize-mb` override engine limits in MB. Increasing limits can increase memory, CPU and runtime; engine hard limits still apply. A positive data count alone does not prove every archive entry was inspected.
-
-Read-only host and Docker filesystem malware scanning using the locally installed ClamAV signature engine. Requires Linux, Python 3.8+, `clamscan`, updated ClamAV databases, and the Docker CLI for container scanning. Run on the Docker host with a local Unix socket context. Root access normally provides the required file/socket access.
-
-On Debian/Ubuntu, install prerequisites using your normal package-management policy:
-
-```sh
-sudo apt-get update
-sudo apt-get install python3 clamav clamav-freshclam
-```
-
-Ensure the ClamAV databases have downloaded before scanning. Use your distribution's freshclam service, or `sudo freshclam` if that service is not already managing updates. The scanner does not install software, change services, or update databases automatically. Docker must already be installed if you use it.
-
-Copy this folder onto the server, then run:
-
-```sh
-sudo python3 devshield_linux.py
-```
-
-Console messages identify each stage and show a heartbeat every 10 seconds during long scans. Verbose file-level progress is saved to each stage's log; inspect a log with `tail -f /path/printed/by/script.log`. JSON results are checkpointed after every completed scan and on interruption, under `/var/log/devshield/<run>/report.json`.
-
-```sh
-# Check a small directory first
-sudo python3 devshield_linux.py --host-root /srv/project --skip-docker
-
-# Containers and volumes only
-sudo python3 devshield_linux.py --skip-host
-
-# Use a scratch disk with room for the largest container filesystem export
-sudo python3 devshield_linux.py --temp-dir /mnt/scratch --heartbeat 5
-```
-
-Host scanning starts at `/` and traverses mounted filesystems, including potentially slow network mounts. `/proc`, `/sys`, `/dev`, `/run`, raw default Docker/containerd storage, the report directory and scratch directory are excluded. No symlinks are followed. Custom Docker storage may be scanned twice. Logs can be large and contain private file paths; keep them private.
-
-For each running container the script uses `docker export`, scans the resulting TAR as an archive, then deletes only its own temporary export. It does not execute programs inside containers, extract archives, stop containers or change their files. It separately scans bind-mount sources and discovered Docker volumes, including unused volumes. Remote daemons are rejected. Volume plugins/network-backed volumes may need separate mounting and scanning. If using a local socket proxy to a remote daemon, do not use this script: mount paths must refer to this machine.
-
-Stopped containers, unused image layers, RAM, kernel state and rootkits are not covered. ClamAV's configured/default size, archive and recursion limits still apply, including to large container TAR exports; a successful scan can miss content past those limits. Review ClamAV summaries and warnings in every log. This is a best-effort filesystem scan, not a comprehensive compromise assessment. Live files can change during scanning. Use a trusted rescue environment for suspected root-level compromise.
-
-Exit status: 0 = no signature detections reported and no recorded orchestration errors; 1 = detections; 2 = incomplete/error (detections may also exist; always inspect the report). No deletion or quarantine is requested. Reports persist if Docker scanning fails or the scan is interrupted with Ctrl+C. A forced kill or power loss may lose the active stage, but earlier checkpoints remain.
-
-Validation on the development Windows machine covers syntax and mocked orchestration only. A real Linux/Docker/ClamAV integration scan must be validated on your server before operational use.
+Metadata-Version: 2.4
+Name: devshield-scanner
+Version: 0.2.0
+Summary: Linux host/Docker inspection with opt-in response for detected process executables
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# DevShield for Linux
+
+## Process-first response (0.2.0)
+
+`sudo /opt/devshield/bin/devshield --remediate-running` first snapshots and scans running executables, sends SIGKILL to signature-detected processes, and attempts to move matching host executables into `/var/lib/devshield/quarantine`. It then scans host files and Docker data. Without this flag, scanning remains read-only. This is an experimental opt-in response mode and can interrupt production services. Process response currently requires root and Python/Linux pidfd support (normally Python 3.9+ and Linux 5.3+).
+
+Heuristic, PUA, encrypted-content, scan-limit and EICAR test alerts never trigger automatic process response. Evidence copies and action records are saved before termination. PID 1, DevShield and its ancestors are excluded. Original-file moves require a matching inode and a same-filesystem rename; failures are reported rather than falling back to destructive copy/delete. Container executables are not moved: rebuild affected containers from trusted images. Supervisors may restart terminated processes. Script interpreters, injected code, memory-only malware and persistence are not comprehensively inspected, and files found during the subsequent host/container scan are not automatically removed. Quarantine samples must not be executed. Quarantine is excluded from later scans.
+
+`--max-files 200000` raises the archive member-count limit when needed. Example for the large container export discussed during validation: `devshield --remediate-running --max-files 200000 --max-filesize-mb 1536 --max-scansize-mb 2048`. Limits do not apply to process snapshots, which retain ClamAV defaults with limit alerts. Increasing limits raises resource use. A privileged attacker can still evade or interfere with live-host inspection. There is no guarantee of complete malware removal.
+
+An installable Python CLI package is included. The Python distribution is `devshield-scanner`; the command is `devshield`. See **INSTALL.md** for isolated installation under `/opt/devshield`. `devshield --version` displays the CLI version.
+
+Version 0.1.1 enables ClamAV scan-limit alerts and marks zero-data scans, missing summaries and logged warnings/errors as incomplete coverage (exit 2), even when ClamAV returns 0. Limit alerts are not proof of malware. Optional `--max-filesize-mb` and `--max-scansize-mb` override engine limits in MB. Increasing limits can increase memory, CPU and runtime; engine hard limits still apply. A positive data count alone does not prove every archive entry was inspected.
+
+Read-only host and Docker filesystem malware scanning using the locally installed ClamAV signature engine. Requires Linux, Python 3.8+, `clamscan`, updated ClamAV databases, and the Docker CLI for container scanning. Run on the Docker host with a local Unix socket context. Root access normally provides the required file/socket access.
+
+On Debian/Ubuntu, install prerequisites using your normal package-management policy:
+
+```sh
+sudo apt-get update
+sudo apt-get install python3 clamav clamav-freshclam
+```
+
+Ensure the ClamAV databases have downloaded before scanning. Use your distribution's freshclam service, or `sudo freshclam` if that service is not already managing updates. The scanner does not install software, change services, or update databases automatically. Docker must already be installed if you use it.
+
+Copy this folder onto the server, then run:
+
+```sh
+sudo python3 devshield_linux.py
+```
+
+Console messages identify each stage and show a heartbeat every 10 seconds during long scans. Verbose file-level progress is saved to each stage's log; inspect a log with `tail -f /path/printed/by/script.log`. JSON results are checkpointed after every completed scan and on interruption, under `/var/log/devshield/<run>/report.json`.
+
+```sh
+# Check a small directory first
+sudo python3 devshield_linux.py --host-root /srv/project --skip-docker
+
+# Containers and volumes only
+sudo python3 devshield_linux.py --skip-host
+
+# Use a scratch disk with room for the largest container filesystem export
+sudo python3 devshield_linux.py --temp-dir /mnt/scratch --heartbeat 5
+```
+
+Host scanning starts at `/` and traverses mounted filesystems, including potentially slow network mounts. `/proc`, `/sys`, `/dev`, `/run`, raw default Docker/containerd storage, the report directory and scratch directory are excluded. No symlinks are followed. Custom Docker storage may be scanned twice. Logs can be large and contain private file paths; keep them private.
+
+For each running container the script uses `docker export`, scans the resulting TAR as an archive, then deletes only its own temporary export. It does not execute programs inside containers, extract archives, stop containers or change their files. It separately scans bind-mount sources and discovered Docker volumes, including unused volumes. Remote daemons are rejected. Volume plugins/network-backed volumes may need separate mounting and scanning. If using a local socket proxy to a remote daemon, do not use this script: mount paths must refer to this machine.
+
+Stopped containers, unused image layers, RAM, kernel state and rootkits are not covered. ClamAV's configured/default size, archive and recursion limits still apply, including to large container TAR exports; a successful scan can miss content past those limits. Review ClamAV summaries and warnings in every log. This is a best-effort filesystem scan, not a comprehensive compromise assessment. Live files can change during scanning. Use a trusted rescue environment for suspected root-level compromise.
+
+Exit status: 0 = no signature detections reported and no recorded orchestration errors; 1 = detections; 2 = incomplete/error (detections may also exist; always inspect the report). No deletion or quarantine is requested. Reports persist if Docker scanning fails or the scan is interrupted with Ctrl+C. A forced kill or power loss may lose the active stage, but earlier checkpoints remain.
+
+Validation on the development Windows machine covers syntax and mocked orchestration only. A real Linux/Docker/ClamAV integration scan must be validated on your server before operational use.

{devshield_scanner-0.1.1 → devshield_scanner-0.2.0}/devshield_scanner.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 LICENSE
 README.md
 devshield_linux.py
+devshield_processes.py
 pyproject.toml
 devshield_scanner.egg-info/PKG-INFO
 devshield_scanner.egg-info/SOURCES.txt

devshield_scanner-0.2.0/devshield_scanner.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+devshield_linux
+devshield_processes

{devshield_scanner-0.1.1 → devshield_scanner-0.2.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "devshield-scanner"
-version = "0.1.1"
-description = "Read-only Linux host and Docker filesystem inspection using ClamAV"
+version = "0.2.0"
+description = "Linux host/Docker inspection with opt-in response for detected process executables"
 readme = "README.md"
 requires-python = ">=3.8"
 dependencies = []
@@ -22,4 +22,4 @@ classifiers = [
 devshield = "devshield_linux:main"
 
 [tool.setuptools]
-py-modules = ["devshield_linux"]
+py-modules = ["devshield_linux", "devshield_processes"]

devshield_scanner-0.1.1/devshield_scanner.egg-info/top_level.txt

@@ -1 +0,0 @@
-devshield_linux