devshield-scanner 0.1.0__py3-none-any.whl

devshield_linux.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""Read-only Linux host/Docker filesystem scan using the installed ClamAV engine."""
+import argparse
+import contextlib
+import datetime as dt
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--version', action='version', version='DevShield 0.1.0')
+    parser.add_argument('--host-root', default='/', help='Host directory to scan (default /)')
+    parser.add_argument('--skip-host', action='store_true')
+    parser.add_argument('--skip-docker', action='store_true')
+    parser.add_argument('--reports', default='/var/log/devshield')
+    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 not sys.platform.startswith('linux'):
+        parser.error('Run this script on Linux.')
+    if args.heartbeat < 1:
+        parser.error('--heartbeat 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()))
+    report_dir.mkdir(parents=True, mode=0o700)
+    report = {'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.',
+                              'Container exports omit volume/bind contents; local mount sources are scanned separately.',
+                              'ClamAV archive, file size and recursion limits apply; encrypted/unreadable content may be missed.',
+                              'Virtual filesystems and raw Docker storage are excluded from the host scan.']}
+    def save():
+        tmp = report_dir / 'report.json.tmp'
+        tmp.write_text(json.dumps(report, indent=2) + '\n')
+        tmp.replace(report_dir / 'report.json')
+    def issue(message):
+        print('COVERAGE ISSUE: ' + message, flush=True)
+        report['issues'].append(message)
+        save()
+    def run(command, label, output=None):
+        """Save output directly to disk, and keep console alive without buffering logs in RAM."""
+        index = len(list(report_dir.glob('*.log')))
+        log = report_dir / f'{index:04d}.log'
+        print(f'START {label} | log: {log}', flush=True)
+        start = time.monotonic()
+        with log.open('wb') as stderr:
+            with (open(output, 'wb') if output else contextlib.nullcontext(stderr)) as stdout:
+                proc = subprocess.Popen(command, stdout=stdout, stderr=stderr)
+                try:
+                    while True:
+                        try:
+                            rc = proc.wait(timeout=args.heartbeat)
+                            break
+                        except subprocess.TimeoutExpired:
+                            print(f'WORKING {label} | elapsed {int(time.monotonic()-start)}s | log bytes {log.stat().st_size}', flush=True)
+                except BaseException:
+                    proc.terminate()
+                    try:
+                        proc.wait(timeout=10)
+                    except subprocess.TimeoutExpired:
+                        proc.kill()
+                        proc.wait()
+                    raise
+        print(f'FINISHED {label} | exit {rc}', flush=True)
+        return rc, str(log)
+    def docker_json(command):
+        result = subprocess.run(['docker', *command], capture_output=True, text=True)
+        if result.returncode:
+            raise RuntimeError(result.stderr.strip() or 'Docker command failed')
+        return json.loads(result.stdout)
+    scratch = tempfile.TemporaryDirectory(prefix='devshield-', dir=args.temp_dir)
+    def scan(path, label, excludes=()):
+        command = ['clamscan', '--recursive=yes', '--infected', '--verbose', '--scan-archive=yes',
+                   '--cross-fs=yes', '--follow-dir-symlinks=0', '--follow-file-symlinks=0']
+        command.extend('--exclude-dir=^' + re.escape(str(Path(p).resolve())) + r'(/|$)' for p in excludes)
+        rc, log = run([*command, '--', str(path)], label)
+        report['scans'].append({'target': str(path), 'label': label, 'exit_code': rc, 'log': log,
+                                'result': {0: 'No signature detections reported', 1: 'Detection reported'}.get(rc, 'Scan error')})
+        save()
+        if rc not in (0, 1):
+            issue(f'{label}: ClamAV failed; see {log}')
+    save()
+    try:
+        if os.geteuid() != 0:
+            issue('Not running as root; protected host files and Docker access may be unavailable.')
+        version = subprocess.run(['clamscan', '--version'], capture_output=True, text=True)
+        report['engine'] = version.stdout.strip()
+        save()
+        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])
+        if not args.skip_docker:
+            if not shutil.which('docker'):
+                issue('Docker CLI missing; containers and volumes were not inspected.')
+            else:
+                try:
+                    info = docker_json(['info', '--format', '{{json .}}'])
+                    if info.get('OSType') != 'linux':
+                        raise RuntimeError('Docker daemon is not Linux.')
+                    context = docker_json(['context', 'inspect'])
+                    endpoint = context[0]['Endpoints']['docker']['Host']
+                    if os.environ.get('DOCKER_HOST') or not endpoint.startswith('unix://'):
+                        raise RuntimeError('Use a local Unix socket Docker context and unset DOCKER_HOST; remote mount paths cannot be safely scanned locally.')
+                    ids = subprocess.run(['docker', 'ps', '-q', '--no-trunc'], capture_output=True, text=True, check=True).stdout.split()
+                    report['running_containers'] = ids
+                    mounts = set()
+                    for cid in ids:
+                        try:
+                            container = docker_json(['inspect', cid])[0]
+                            mounts.update(m['Source'] for m in container.get('Mounts', []) if m.get('Source'))
+                            archive = Path(scratch.name) / (cid + '.tar')
+                            rc, log = run(['docker', 'export', cid], 'Export container ' + cid, archive)
+                            if rc:
+                                issue(f'Container {cid} export failed; see {log}')
+                            else:
+                                scan(archive, 'Container filesystem ' + cid)
+                            archive.unlink(missing_ok=True)
+                        except (OSError, RuntimeError, ValueError, subprocess.SubprocessError) as exc:
+                            issue(f'Container {cid}: {exc}')
+                    # Include unused local volumes as well as mounts from running containers.
+                    volume_names = subprocess.run(['docker', 'volume', 'ls', '-q'], capture_output=True, text=True, check=True).stdout.split()
+                    for name in volume_names:
+                        try:
+                            volume = docker_json(['volume', 'inspect', name])[0]
+                            if volume.get('Driver') != 'local' or volume.get('Options'):
+                                issue(f'Volume {name}: external/plugin/configured volume may require separate scanning.')
+                            if volume.get('Mountpoint'):
+                                mounts.add(volume['Mountpoint'])
+                        except (RuntimeError, ValueError) as exc:
+                            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])
+                        else:
+                            issue('Docker mount source inaccessible: ' + source)
+                except (OSError, RuntimeError, ValueError, KeyError, subprocess.SubprocessError) as exc:
+                    issue('Docker discovery failed: ' + str(exc))
+    except KeyboardInterrupt:
+        issue('Interrupted; scan is incomplete.')
+    except Exception as exc:
+        issue('Scan aborted: ' + str(exc))
+    finally:
+        scratch.cleanup()
+        report['finished'] = dt.datetime.now(dt.timezone.utc).isoformat()
+        save()
+        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
+
+
+if __name__ == '__main__':
+    sys.exit(main())

devshield_scanner-0.1.0.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: devshield-scanner
+Version: 0.1.0
+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. See **INSTALL.md** to build a wheel and install the `devshield` command on servers using an isolated environment under `/opt/devshield`. There is no published npm or Python registry package yet. `devshield --version` displays the CLI version; existing scanner flags are unchanged.
+
+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.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+devshield_linux.py,sha256=-8FTc3FIYD4AmxuGxCT12izIPytpmnQ-YobyewYQ-xs,9343
+devshield_scanner-0.1.0.dist-info/licenses/LICENSE,sha256=s-XxIzkqir-HOLNTj5GGiMGroYKQg0jNLePiE6l3RLA,1079
+devshield_scanner-0.1.0.dist-info/METADATA,sha256=j8SlJK0iWM3yqlaDSjJ0Uk7osnDbW76uUNJG2wckCOs,4459
+devshield_scanner-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+devshield_scanner-0.1.0.dist-info/entry_points.txt,sha256=ahqb5UoqMVnfLlu6dw2yCOdoE-Oqf2rzLz0w7j_iMNU,51
+devshield_scanner-0.1.0.dist-info/top_level.txt,sha256=6JS_zDOzXEumr3xF-CcuEnhbdrYP0EkNpehijbeWSwE,16
+devshield_scanner-0.1.0.dist-info/RECORD,,

devshield_scanner-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

devshield_scanner-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+devshield = devshield_linux:main

devshield_scanner-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DevShield contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

devshield_scanner-0.1.0.dist-info/top_level.txt

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