devshield-scanner 0.2.1__tar.gz → 0.3.0__tar.gz

{devshield_scanner-0.2.1/devshield_scanner.egg-info → devshield_scanner-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devshield-scanner
-Version: 0.2.1
+Version: 0.3.0
 Summary: Linux host/Docker inspection with opt-in response for detected process executables
 License-Expression: MIT
 Classifier: Development Status :: 3 - Alpha
@@ -14,9 +14,13 @@ Dynamic: license-file
 
 # DevShield for Linux
 
-0.2.1 fixes custom scan-limit propagation: `--max-filesize-mb`, `--max-scansize-mb`, and `--max-files` now apply to running-process snapshots as well as filesystem/container scans. Use `--remediate-running --skip-host --skip-docker` to run only the process stage. This remains an opt-in mode that can interrupt services.
+0.3.0 adds `--quick-scan` to inspect running process executables only, using the installed ClamAV signatures. Actionable detections are terminated and host binaries are quarantined through the existing conservative response. It requires root and can interrupt services. Runtime depends on the number and size of unique process executables and may take longer than a few seconds.
 
-## Process-first response (0.2.0)
+0.2.1 fixes custom scan-limit propagation: `--max-filesize-mb`, `--max-scansize-mb`, and `--max-files` now apply to running-process snapshots as well as filesystem/container scans.
+
+## Quick scan and process response
+
+Quick process scan: run `sudo /opt/devshield/bin/devshield --quick-scan`. It inspects running process executables only using the local ClamAV database, then exits without scanning host folders or Docker. Actionable signature detections use the existing conservative response: preserve evidence, terminate the process, and quarantine the matching host binary. This requires root and Python/Linux pidfd support. It may take longer than a few seconds depending on process count and executable sizes. Update signatures separately with `sudo freshclam` or your distribution's database updater.
 
 `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+).
 
@@ -24,7 +28,7 @@ Heuristic, PUA, encrypted-content, scan-limit and EICAR test alerts never trigge
 
 `--max-files 200000` raises the archive member-count limit when needed. 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.
+The Python distribution is `devshield-scanner`; the command is `devshield`. Version 0.3.0 adds `devshield --quick-scan`, which scans running process executables only and uses the conservative process response for actionable ClamAV signature detections. See **INSTALL.md** for installation and upgrade instructions. `devshield --version` displays the installed 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.
 
@@ -43,6 +47,9 @@ Copy this folder onto the server, then run:
 
 ```sh
 sudo python3 devshield_linux.py
+
+# Process-only signature scan and response
+sudo python3 devshield_linux.py --quick-scan
 ```
 
 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`.
@@ -64,6 +71,6 @@ For each running container the script uses `docker export`, scans the resulting
 
 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.
+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). The default scan is read-only. `--quick-scan` and `--remediate-running` can terminate detected processes and quarantine matching host executables. 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.2.1 → devshield_scanner-0.3.0}/README.md

@@ -1,8 +1,12 @@
 # DevShield for Linux
 
-0.2.1 fixes custom scan-limit propagation: `--max-filesize-mb`, `--max-scansize-mb`, and `--max-files` now apply to running-process snapshots as well as filesystem/container scans. Use `--remediate-running --skip-host --skip-docker` to run only the process stage. This remains an opt-in mode that can interrupt services.
+0.3.0 adds `--quick-scan` to inspect running process executables only, using the installed ClamAV signatures. Actionable detections are terminated and host binaries are quarantined through the existing conservative response. It requires root and can interrupt services. Runtime depends on the number and size of unique process executables and may take longer than a few seconds.
 
-## Process-first response (0.2.0)
+0.2.1 fixes custom scan-limit propagation: `--max-filesize-mb`, `--max-scansize-mb`, and `--max-files` now apply to running-process snapshots as well as filesystem/container scans.
+
+## Quick scan and process response
+
+Quick process scan: run `sudo /opt/devshield/bin/devshield --quick-scan`. It inspects running process executables only using the local ClamAV database, then exits without scanning host folders or Docker. Actionable signature detections use the existing conservative response: preserve evidence, terminate the process, and quarantine the matching host binary. This requires root and Python/Linux pidfd support. It may take longer than a few seconds depending on process count and executable sizes. Update signatures separately with `sudo freshclam` or your distribution's database updater.
 
 `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+).
 
@@ -10,7 +14,7 @@ Heuristic, PUA, encrypted-content, scan-limit and EICAR test alerts never trigge
 
 `--max-files 200000` raises the archive member-count limit when needed. 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.
+The Python distribution is `devshield-scanner`; the command is `devshield`. Version 0.3.0 adds `devshield --quick-scan`, which scans running process executables only and uses the conservative process response for actionable ClamAV signature detections. See **INSTALL.md** for installation and upgrade instructions. `devshield --version` displays the installed 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.
 
@@ -29,6 +33,9 @@ Copy this folder onto the server, then run:
 
 ```sh
 sudo python3 devshield_linux.py
+
+# Process-only signature scan and response
+sudo python3 devshield_linux.py --quick-scan
 ```
 
 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`.
@@ -50,6 +57,6 @@ For each running container the script uses `docker export`, scans the resulting
 
 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.
+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). The default scan is read-only. `--quick-scan` and `--remediate-running` can terminate detected processes and quarantine matching host executables. 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.2.1 → devshield_scanner-0.3.0}/devshield_linux.py

@@ -47,7 +47,8 @@ def coverage_warnings(log_path):
 
 def main():
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument('--version', action='version', version='DevShield 0.2.1')
+    parser.add_argument('--version', action='version', version='DevShield 0.3.0')
+    parser.add_argument('--quick-scan', action='store_true', help='scan running process executables only; terminate actionable signature detections and quarantine host binaries')
     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')
@@ -60,6 +61,8 @@ def main():
     parser.add_argument('--temp-dir', help='Scratch filesystem with enough space for container exports')
     parser.add_argument('--heartbeat', type=int, default=10)
     args = parser.parse_args()
+    if args.quick_scan and args.remediate_running:
+        parser.error('Choose either --quick-scan or --remediate-running, not both.')
     scan_options = clamav_limits(args)
     if not sys.platform.startswith('linux'):
         parser.error('Run this script on Linux.')
@@ -72,7 +75,8 @@ def main():
         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()))
     report_dir.mkdir(parents=True, mode=0o700)
-    report = {'started': dt.datetime.now(dt.timezone.utc).isoformat(), 'scans': [], 'issues': [],
+    report = {'version': '0.3.0', 'mode': 'quick-process-scan' if args.quick_scan else 'full-scan',
+              'started': dt.datetime.now(dt.timezone.utc).isoformat(), 'scans': [], 'issues': [],
               'limitations': ['Filesystem signature scan, not proof of absence of malware or rootkits.',
                               'Files can change during live scans; no atomic snapshot is taken.',
                               'Stopped containers and unused image layers are not exported.',
@@ -142,15 +146,17 @@ def main():
         version = subprocess.run(['clamscan', '--version'], capture_output=True, text=True)
         report['engine'] = version.stdout.strip()
         save()
-        if args.remediate_running:
+        if args.quick_scan or args.remediate_running:
+            if args.quick_scan:
+                print('[Quick Scan] Scanning running process executables only; signature-confirmed responses may terminate processes.', flush=True)
             inspect_running(run, issue, save, report, scratch.name, args.quarantine, coverage_warnings, scan_options)
-        if not args.skip_host:
+        if not args.quick_scan and 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, args.quarantine])
-        if not args.skip_docker:
+        if not args.quick_scan and not args.skip_docker:
             if not shutil.which('docker'):
                 issue('Docker CLI missing; containers and volumes were not inspected.')
             else:

{devshield_scanner-0.2.1 → devshield_scanner-0.3.0/devshield_scanner.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devshield-scanner
-Version: 0.2.1
+Version: 0.3.0
 Summary: Linux host/Docker inspection with opt-in response for detected process executables
 License-Expression: MIT
 Classifier: Development Status :: 3 - Alpha
@@ -14,9 +14,13 @@ Dynamic: license-file
 
 # DevShield for Linux
 
-0.2.1 fixes custom scan-limit propagation: `--max-filesize-mb`, `--max-scansize-mb`, and `--max-files` now apply to running-process snapshots as well as filesystem/container scans. Use `--remediate-running --skip-host --skip-docker` to run only the process stage. This remains an opt-in mode that can interrupt services.
+0.3.0 adds `--quick-scan` to inspect running process executables only, using the installed ClamAV signatures. Actionable detections are terminated and host binaries are quarantined through the existing conservative response. It requires root and can interrupt services. Runtime depends on the number and size of unique process executables and may take longer than a few seconds.
 
-## Process-first response (0.2.0)
+0.2.1 fixes custom scan-limit propagation: `--max-filesize-mb`, `--max-scansize-mb`, and `--max-files` now apply to running-process snapshots as well as filesystem/container scans.
+
+## Quick scan and process response
+
+Quick process scan: run `sudo /opt/devshield/bin/devshield --quick-scan`. It inspects running process executables only using the local ClamAV database, then exits without scanning host folders or Docker. Actionable signature detections use the existing conservative response: preserve evidence, terminate the process, and quarantine the matching host binary. This requires root and Python/Linux pidfd support. It may take longer than a few seconds depending on process count and executable sizes. Update signatures separately with `sudo freshclam` or your distribution's database updater.
 
 `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+).
 
@@ -24,7 +28,7 @@ Heuristic, PUA, encrypted-content, scan-limit and EICAR test alerts never trigge
 
 `--max-files 200000` raises the archive member-count limit when needed. 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.
+The Python distribution is `devshield-scanner`; the command is `devshield`. Version 0.3.0 adds `devshield --quick-scan`, which scans running process executables only and uses the conservative process response for actionable ClamAV signature detections. See **INSTALL.md** for installation and upgrade instructions. `devshield --version` displays the installed 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.
 
@@ -43,6 +47,9 @@ Copy this folder onto the server, then run:
 
 ```sh
 sudo python3 devshield_linux.py
+
+# Process-only signature scan and response
+sudo python3 devshield_linux.py --quick-scan
 ```
 
 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`.
@@ -64,6 +71,6 @@ For each running container the script uses `docker export`, scans the resulting
 
 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.
+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). The default scan is read-only. `--quick-scan` and `--remediate-running` can terminate detected processes and quarantine matching host executables. 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.2.1 → devshield_scanner-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "devshield-scanner"
-version = "0.2.1"
+version = "0.3.0"
 description = "Linux host/Docker inspection with opt-in response for detected process executables"
 readme = "README.md"
 requires-python = ">=3.8"