webshell-analyzer 1.0.0__py3-none-any.whl

webshell_analyzer/extractor/ast_extraction/vendor/nikic/php-parser/lib/PhpParser/Token.php

@@ -0,0 +1,18 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser;
+
+/**
+ * A PHP token. On PHP 8.0 this extends from PhpToken.
+ */
+class Token extends Internal\TokenPolyfill {
+    /** Get (exclusive) zero-based end position of the token. */
+    public function getEndPos(): int {
+        return $this->pos + \strlen($this->text);
+    }
+
+    /** Get 1-based end line number of the token. */
+    public function getEndLine(): int {
+        return $this->line + \substr_count($this->text, "\n");
+    }
+}

webshell_analyzer/extractor/ast_extraction/vendor/nikic/php-parser/lib/PhpParser/compatibility_tokens.php

@@ -0,0 +1,71 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser;
+
+if (!\function_exists('PhpParser\defineCompatibilityTokens')) {
+    function defineCompatibilityTokens(): void {
+        $compatTokens = [
+            // PHP 8.0
+            'T_NAME_QUALIFIED',
+            'T_NAME_FULLY_QUALIFIED',
+            'T_NAME_RELATIVE',
+            'T_MATCH',
+            'T_NULLSAFE_OBJECT_OPERATOR',
+            'T_ATTRIBUTE',
+            // PHP 8.1
+            'T_ENUM',
+            'T_AMPERSAND_NOT_FOLLOWED_BY_VAR_OR_VARARG',
+            'T_AMPERSAND_FOLLOWED_BY_VAR_OR_VARARG',
+            'T_READONLY',
+            // PHP 8.4
+            'T_PROPERTY_C',
+            'T_PUBLIC_SET',
+            'T_PROTECTED_SET',
+            'T_PRIVATE_SET',
+            // PHP 8.5
+            'T_PIPE',
+            'T_VOID_CAST',
+        ];
+
+        // PHP-Parser might be used together with another library that also emulates some or all
+        // of these tokens. Perform a sanity-check that all already defined tokens have been
+        // assigned a unique ID.
+        $usedTokenIds = [];
+        foreach ($compatTokens as $token) {
+            if (\defined($token)) {
+                $tokenId = \constant($token);
+                if (!\is_int($tokenId)) {
+                    throw new \Error(sprintf(
+                        'Token %s has ID of type %s, should be int. ' .
+                        'You may be using a library with broken token emulation',
+                        $token, \gettype($tokenId)
+                    ));
+                }
+                $clashingToken = $usedTokenIds[$tokenId] ?? null;
+                if ($clashingToken !== null) {
+                    throw new \Error(sprintf(
+                        'Token %s has same ID as token %s, ' .
+                        'you may be using a library with broken token emulation',
+                        $token, $clashingToken
+                    ));
+                }
+                $usedTokenIds[$tokenId] = $token;
+            }
+        }
+
+        // Now define any tokens that have not yet been emulated. Try to assign IDs from -1
+        // downwards, but skip any IDs that may already be in use.
+        $newTokenId = -1;
+        foreach ($compatTokens as $token) {
+            if (!\defined($token)) {
+                while (isset($usedTokenIds[$newTokenId])) {
+                    $newTokenId--;
+                }
+                \define($token, $newTokenId);
+                $newTokenId--;
+            }
+        }
+    }
+
+    defineCompatibilityTokens();
+}

webshell_analyzer/extractor/extractor.py

@@ -0,0 +1,73 @@
+import os
+import subprocess
+import json
+from webshell_analyzer.extractor.statistical_extraction.statisticalExtractor import extract_statistical_features
+from webshell_analyzer.extractor.lexical_extraction.lexicalExtractor import extract_lexical_features
+from webshell_analyzer.model.model_loader import load_feature_columns
+
+feature_columns = load_feature_columns()
+
+base_dir = os.path.dirname(os.path.dirname(__file__))
+
+def extract_ast(filepath):
+    #call the AST extractor script
+    php_ast_path = os.path.abspath(os.path.join(base_dir, "extractor", "ast_extraction", "src", "astExtractor.php"))
+    target_file = os.path.abspath(filepath)
+
+    try:
+        result = subprocess.run(["php", php_ast_path, target_file], capture_output=True, text=True)
+
+        #Handle errors if the PHP script execution fails
+        if result.returncode != 0:
+            return None
+        
+        try:
+            return json.loads(result.stdout)
+        
+        #error handling for invalid JSON output from the PHP script
+        except json.JSONDecodeError:
+            print(f"[WARNING] invalid ast output")
+
+    except Exception:
+        return None
+
+
+def align_features(features_dict):
+    return [features_dict.get(col, 0) for col in feature_columns]
+
+
+def extract_features(filepath):
+    features = {}
+
+    #Extract AST features
+    ast_features = extract_ast(filepath)
+    if ast_features is not None:
+        features.update(ast_features)
+
+   
+    try:
+        #read file content for lexical and statistical extraction
+        with open(filepath, "r", encoding="utf-8", errors="ignore") as f:
+            code = f.read().strip()
+    except Exception:
+        print("[ERROR] Failed to read file")
+        return None
+
+    try:
+        #extract lexical features
+        lexical_features = extract_lexical_features(code)
+        features.update(lexical_features)
+    except Exception:
+        print("[WARNING] Lexical feature extraction failed")
+
+    try:
+        #extract statistical features
+        statistical_features = extract_statistical_features(code)
+        features.update(statistical_features)
+    except Exception:
+        print("[WARNING] statistical feature extraction failed")
+
+    if not features:
+        return None
+
+    return features

webshell_analyzer/extractor/lexical_extraction/lexicalExtractor.py

@@ -0,0 +1,31 @@
+import re
+
+DANGEROUS_FUNCS = ["eval", "system", "exec"]
+USER_INPUTS = [r"\$_POST", r"\$_REQUEST", r"\$_FILES"]
+INCLUDE_FUNCS = ["require_once"]
+SYMBOL_PATTERN = r"[{}\[\]\(\);$]"
+
+
+def count_regex(pattern, text):
+    return len(re.findall(pattern, text, flags=re.IGNORECASE))
+
+
+def extract_lexical_features(code):
+    features = {}
+    #dangerous functions
+    for f in DANGEROUS_FUNCS:
+        features[f"lex_func_{f}"] = count_regex(rf"\b{f}\b", code)
+
+    #user input variable
+    for var in USER_INPUTS:
+        clean_name = var.replace("\\", "").replace("$", "")
+        features[f"lex_input_{clean_name}"] = count_regex(var, code)
+
+    #include function
+    for inc in INCLUDE_FUNCS:
+        features[f"lex_include_{inc}"] = count_regex(rf"\b{inc}\b", code)
+
+    #special symbols
+    features["lex_symbol_count"] = count_regex(SYMBOL_PATTERN, code)
+
+    return features

webshell_analyzer/extractor/statistical_extraction/statisticalExtractor.py

@@ -0,0 +1,60 @@
+import re
+import math
+import zlib
+from collections import Counter
+
+#calculate shannon entropy from PHP code
+def calculate_entropy(text):
+    if not text:
+        return 0.0
+    
+    counter = Counter(text)
+    length = len(text)
+
+    #shanon entropy formula
+    return -sum(
+        (count / length) * math.log2(count / length)
+        for count in counter.values()
+    )
+
+def compression_ratio(text):
+    if not text:
+        return 0.0
+    
+    #convert text into bytes before compression
+    encoded = text.encode("utf-8", errors="ignore")
+    
+    if len(encoded) == 0:
+        return 0.0
+    
+    #compress text using zlib
+    compressed = zlib.compress(encoded)
+    return len(compressed) / len(encoded)
+
+#extract statistical features from PHP code
+def extract_statistical_features(php_code):
+    if not isinstance(php_code, str):
+        php_code = ""
+
+    length = len(php_code)
+
+    features = {
+        "stat_entropy": 0,
+        "stat_digit_ratio": 0,
+        "stat_symbol_ratio": 0,
+        "stat_compression_ratio": 0
+    }
+
+    if length == 0:
+        return features
+            
+    features["stat_entropy"] = calculate_entropy(php_code)
+    #calculate ratios of numeric characters
+    features["stat_digit_ratio"] = sum(c.isdigit() for c in php_code) / length
+    #calculate ratio of special symbols (non-alphanumeric characters)
+    features["stat_symbol_ratio"] = sum(not c.isalnum() for c in php_code) / length
+    #calculate compression ratio
+    features["stat_compression_ratio"] = compression_ratio(php_code)
+
+    return features
+

webshell_analyzer/model/features_selected.json

@@ -0,0 +1 @@
+["lex_func_eval", "stat_digit_ratio", "classDefExists", "lex_input__POST", "stat_entropy", "dynamicFuncCallExists", "lex_input__FILES", "lex_func_exec", "varUsageCount", "funcDefCount", "lex_symbol_count", "superglobalAsFuncArg", "suspiciousConcat", "lex_include_require_once", "stat_compression_ratio", "stat_symbol_ratio", "varExists", "lex_func_system", "lex_input__REQUEST", "assignmentCount"]

webshell_analyzer/model/model_loader.py

@@ -0,0 +1,19 @@
+import os
+import pickle
+import pandas as pd
+import json
+from joblib import dump, load
+
+
+base_dir = os.path.dirname(os.path.dirname(__file__))
+
+def load_feature_columns():
+    feature_path = os.path.join(base_dir, "model", "features_selected.json")
+    with open(feature_path, "r") as f:
+        cols = json.load(f)
+    return cols
+
+def load_model():
+    model_path = os.path.join(base_dir, "model", "rf_webshell_model.joblib")
+    return load(model_path)
+

webshell_analyzer/modules/detector.py

@@ -0,0 +1,174 @@
+import os
+import sys
+import json
+from colorama import Fore, Style
+import pandas as pd
+from sklearn.inspection import permutation_importance
+from webshell_analyzer.extractor.extractor import extract_features
+from webshell_analyzer.model.model_loader import load_feature_columns, load_model
+
+feature_columns = load_feature_columns()
+model = load_model()
+
+max_file_size = 10_000_000  # 10 MB
+
+def check_file_content(filepath):
+    try:
+        #Read only the first 2000 bytes to check for PHP tags
+        with open(filepath, 'r', encoding='utf-8', errors='ignore') as file:
+            content = file.read(2000).lower()
+
+        #check if the file contains PHP opening tags
+        if "<?php" in content or "<?=" in content:
+            return True
+        else:
+            return False
+    except Exception as e:
+        print(f"[ERROR] Could not read file '{filepath}': {e}")
+        return False
+
+def validate_file(filepath):
+    size = os.path.getsize(filepath)
+
+    #check whether the file is empty 
+    if size == 0:
+        return False, "Empty File, No Content to Analyze"
+    
+    #validate maximum allowed file size
+    if size > max_file_size:
+        return False, "File too Large"
+
+    #check whether the file contains PHP code or not, if not skip the file
+    if not check_file_content(filepath):
+        return False, "No PHP Code Detected"
+    
+    return True, None
+
+
+def processing_file(filepath):
+    is_valid, reason = validate_file(filepath)
+
+    result = {
+        "filepath": filepath,
+        "filename": os.path.basename(filepath),
+        "file_size": os.path.getsize(filepath)
+    }
+
+    #if the file is not valid, return the result with status "invalid" and reason for skipping the file
+    if not is_valid:
+        result.update({
+            "status": "invalid",
+            "prediction": "N/A",
+            "reason": reason,
+        })
+        return result
+    
+    #feature extraction
+    features = extract_features(filepath)
+
+    #return the result with status "error", if feature extraction fails
+    if features is None:
+        result.update({
+            "status": "error",
+            "prediction": "N/A",
+            "reason": "Feature extraction failed",
+        })
+        return result
+
+    features_df = pd.DataFrame([features])
+    features_df = features_df.reindex(columns=feature_columns, fill_value=0)
+
+    #model prediction
+    pred = model.predict(features_df)[0]
+    proba = model.predict_proba(features_df)[0]
+    
+    proba_normal = proba[0]
+    proba_webshell = proba[1]
+
+    #determine the confidence score based on the predicted class with the highest probability
+    if proba_webshell > proba_normal:
+        proba = f"{proba_webshell:.2%}"
+    else:
+        proba = f"{proba_normal:.2%}"
+    
+    label = "webshell" if str(pred).lower() == "webshell" or pred == 1 else "normal"
+
+    result.update({
+        "status": "processed",
+        "prediction": label,
+        "confidence": proba,
+        "features": features
+    })
+
+    return result
+
+#saving the output detection to json file
+def save_result_to_json(result, output_file):
+    if os.path.exists(output_file):
+        with open(output_file, "r") as f:
+            try:
+                data = json.load(f)
+
+                if not isinstance(data, list):
+                    data = [data]
+            except json.JSONDecodeError:
+                data = []
+    else:
+        data = []
+    data.append(result)
+
+    with open(output_file, "w") as f:
+        json.dump(data, f, indent=4)
+
+
+def get_status_color(status):
+    if status == "processed":
+        return Fore.GREEN
+    elif status == "skipped":
+        return Fore.YELLOW
+    elif status == "error":
+        return Fore.RED
+    else:
+        return Fore.CYAN
+    
+def show_save_message(output_file):
+    print(Fore.GREEN + "\n" + "-" * 50)
+    print(Fore.GREEN + f"OUTPUT FILE SAVED".center(50))
+    print(Fore.GREEN + "-" * 50)
+    print(Fore.GREEN + f"Location:  {output_file}")
+    print(Fore.GREEN + "-" * 50)
+    print(Style.RESET_ALL)
+
+
+def detect_file(filepath, output_file=None):
+    result = processing_file(filepath)
+    color = get_status_color(result["status"])
+
+
+    if result["status"] == "processed" and "features" in result:
+        print(color + "\n" + "=" * 50)
+        print(color + "EXTRACTION FEATURES".center(50))
+        print(color + "=" * 50)
+        for k, v in result["features"].items():
+            nilai = f"{v:.4f}" if isinstance(v, float) else str(v)
+            print(color + f"{k:<35} : {nilai}")
+        print(color + "=" * 50 + Style.RESET_ALL)
+    
+    print(color + "\n" + "=" * 50)
+    print(color + "SUMMARY RESULT".center(50))
+    print(color + "=" * 50)
+    print(color + f"Status       : {result['status']}")
+    print(color + f"File Size    : {os.path.getsize(filepath)} bytes")
+    if result["status"] == "processed":
+        print(color + f"Prediction   : {result['prediction'].upper()}")
+        print(color + f"Confidence   : {result['confidence']}")
+    else :
+        print(color + f"Reason       : {result['reason']}")
+    print(color + "=" * 50)
+
+    if output_file:
+        save_result_to_json(result, output_file)
+        show_save_message(output_file)
+    return result
+
+    

webshell_analyzer/modules/scanner.py

@@ -0,0 +1,68 @@
+import os
+import sys 
+from colorama import Style, Fore
+import json
+from webshell_analyzer.modules.detector import processing_file, show_save_message
+
+def scan_directory(directorypath, output_file=None):
+    
+    total_files = 0
+    total_processed_files = 0
+    total_filewebshells = 0
+    total_filenormal = 0
+
+    results = []
+
+    for root, _, files in os.walk(directorypath):
+        for file in files:
+            filepath = os.path.join(root, file)
+            total_files += 1
+            
+            result = processing_file(filepath)
+            
+            results.append(result)
+
+            if result["status"] == "processed":
+                print(Fore.GREEN + f"[{result['prediction'].upper()}] {filepath}")
+                total_processed_files += 1
+                
+                if result["prediction"].lower() == "webshell":
+                    total_filewebshells += 1
+                else :
+                    total_filenormal += 1
+            else:
+                print(Fore.YELLOW + f"[SKIPPED] {result['reason']}: {filepath}")
+
+    summary = {
+        "total files": total_files,
+        "processed_files": total_processed_files,
+        "skipped files": total_files - total_processed_files,
+        "normal files": total_filenormal,
+        "webshell files": total_filewebshells
+    }
+
+    final_output = {
+        "results" : results,
+        "summary": summary
+    }
+
+    print(Fore.GREEN + "\n" + "=" * 50)
+    print(Fore.GREEN + "SCAN SUMMARY".center(50))
+    print(Fore.GREEN + "=" * 50)
+    print(Fore.GREEN + f"Total files: {total_files}")
+    print(Fore.GREEN + f"Processed files: {total_processed_files}")
+    print(Fore.GREEN + f"Skipped files: {total_files - total_processed_files}")
+    print(Fore.GREEN + f"normal files: {total_filenormal}")
+    print(Fore.GREEN + f"webshell files: {total_filewebshells}")
+    print(Fore.GREEN + "=" * 50 + "\n")
+    if output_file:
+        with open(output_file, "w") as f:
+            json.dump(final_output, f, indent=4)
+        show_save_message(output_file)
+
+    sys.stdout.write(Style.RESET_ALL)
+    sys.stdout.flush()
+
+    return output_file, results
+
+

webshell_analyzer-1.0.0.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: webshell-analyzer
+Version: 1.0.0
+Summary: Webshell Detection Tool integrating Machine Learning based on Static Feature Extraction
+Author-email: Adelia Saputri <adelias.dev@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Adelia saputri
+        
+        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.
+        
+Keywords: webshell,detection,machine learning,security,php
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Security
+Classifier: Intended Audience :: System Administrators
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: scikit-learn
+Requires-Dist: colorama
+Requires-Dist: pyfiglet
+Requires-Dist: joblib
+Dynamic: license-file
+
+# Webshell-Analyzer
+![Webshell Analyzer Home Screen](/assets/images/home-screen.png "Home Screen")
+webshell analyzer is command line based webshell detection tool that utillizes static feature extraction and using Random Forest classification to detect malicious PHP webshell.
+
+# Table of Contens
+- About
+- Features
+- Requirements
+- Instalation
+- Usage
+- Commands
+
+# About
+webshell analyzer was developed to assist security analysts, researchers, and system administrators in identifying potentially malicious PHP files before they are executed on a web server. the tool helps to mitigate the risk of unauthorised access, web defacement attacks, and persistent backdoor attacks, which are commonly associated with webshells.
+
+this system combines three static code analysis methods: lexical analysis, statistical analysis, and Abstract Syntax Tree (AST) analysis. this approach enables the detection process to identify suspicious functions, code structure patterns, and statistical characteristics that may indicate malicious behavior.
+
+# Features
+- Scan individual PHP files for webshell indicators
+- Recursively scan entire directories
+- Static feature extraction (no code execution required)
+- Machine learning classification using Random Forest
+- Export results to only JSON file
+- Interactive CLI environment
+
+# Requirements
+before installing and running webshell analyzer, ensure that your system meets the following requirements :
+
+- Python 3.10 or later
+- Pip (oython package manager)
+- Git
+
+**Python Dependencies**
+The required python packages are listed in the ```requirements.txt``` file and can be installed automatically using :
+
+```pip install -r requirements.txt```
+
+# Installation
+to install webshell analyzer, clone this repository to your local machine using the following command :
+
+```git clone https://github.com```
+
+After the installation process is complete, the system is ready to use.
+
+# Usage
+To get started with Webshell Analyzer:
+
+Start ```bash wsanalyzer```:  this is the main command to enter the Webshell Analyzer interactive environment.
+You will be greeted with the Webshell Analyzer prompt:
+
+From here, you can run all available commands such as `scan`, `detect`, `--output`, `help`, `exit`.
+
+# Command
+1. ```scan <directory_path> [--output <output_file.json>]``` -> scan all PHP files in a directory for webshell detection
+2. ```detect <file_path> [--output <output_file.json>]``` -> detect a specific file for webshell activity
+3. ```help``` -> for show this help message
+4. ```exit``` -> For Exit the Webshell Analyzer
+5. ```--output <output_file.json>``` -> Save the detection results to a JSON file
+
+
+
+