multivol 0.1.0__py3-none-any.whl

multivol/api.py

@@ -0,0 +1,1001 @@
+from flask import Flask, request, jsonify, abort
+import argparse
+import os
+import docker
+import threading
+import uuid
+import time
+import sqlite3
+import json
+import glob
+import hashlib
+from werkzeug.utils import secure_filename
+from flask import Flask, request, jsonify, abort, send_from_directory, send_file
+from flask_cors import CORS
+import zipfile
+import io
+
+app = Flask(__name__)
+# Increase max upload size to 16GB (or appropriate limit for dumps)
+app.config['MAX_CONTENT_LENGTH'] = 16 * 1024 * 1024 * 1024 
+CORS(app, resources={r"/*": {"origins": "*"}}) # Explicitly allow all origins
+
+STORAGE_DIR = os.environ.get("STORAGE_DIR", os.path.join(os.getcwd(), "storage"))
+if not os.path.exists(STORAGE_DIR):
+    os.makedirs(STORAGE_DIR)
+
+runner_func = None
+
+@app.route('/health', methods=['GET'])
+def health_check():
+    return jsonify({"status": "ok", "timestamp": time.time()})
+
+@app.before_request
+def restrict_to_localhost():
+    # Allow bypass via environment variable
+    if os.environ.get("DISABLE_LOCALHOST_ONLY"):
+        return
+
+    # Allow 127.0.0.1 and ::1 (IPv6 localhost)
+    allowed_ips = ["127.0.0.1", "::1"]
+    if request.remote_addr not in allowed_ips:
+        abort(403, description="Access forbidden: Only localhost connections allowed, please set DISABLE_LOCALHOST_ONLY=1 to disable this check.")
+
+def init_db():
+    conn = sqlite3.connect('scans.db')
+    c = conn.cursor()
+    c.execute('''CREATE TABLE IF NOT EXISTS scans
+                 (uuid TEXT PRIMARY KEY, status TEXT, mode TEXT, os TEXT, volatility_version TEXT, dump_path TEXT, output_dir TEXT, created_at REAL, error TEXT)''')
+    
+    # New table for results
+    c.execute('''CREATE TABLE IF NOT EXISTS scan_results
+                 (id INTEGER PRIMARY KEY AUTOINCREMENT, scan_id TEXT, module TEXT, content TEXT, created_at REAL,
+                 FOREIGN KEY(scan_id) REFERENCES scans(uuid))''')
+                 
+    # Migration: Check if 'name' column exists
+    try:
+        c.execute("SELECT name FROM scans LIMIT 1")
+    except sqlite3.OperationalError:
+        print("[INFO] Migrating DB: Adding 'name' column to scans table")
+        c.execute("ALTER TABLE scans ADD COLUMN name TEXT")
+
+    # Migration: Check if 'image' column exists (New for file download)
+    try:
+        c.execute("SELECT image FROM scans LIMIT 1")
+    except sqlite3.OperationalError:
+        print("[INFO] Migrating DB: Adding 'image' column to scans table")
+        c.execute("ALTER TABLE scans ADD COLUMN image TEXT")
+
+    # Table for async dump tasks
+    c.execute('''CREATE TABLE IF NOT EXISTS dump_tasks
+                 (task_id TEXT PRIMARY KEY, scan_id TEXT, status TEXT, output_path TEXT, error TEXT, created_at REAL)''')
+
+    conn.commit()
+    conn.close()
+
+init_db()
+
+@app.route('/scans/<uuid>', methods=['PUT'])
+def rename_scan(uuid):
+    data = request.json
+    new_name = data.get('name')
+    if not new_name:
+        return jsonify({"error": "Name is required"}), 400
+        
+    conn = sqlite3.connect('scans.db')
+    c = conn.cursor()
+    c.execute("UPDATE scans SET name = ? WHERE uuid = ?", (new_name, uuid))
+    conn.commit()
+    conn.close()
+    return jsonify({"status": "updated"})
+
+@app.route('/scans/<uuid>', methods=['DELETE'])
+def delete_scan(uuid):
+    conn = sqlite3.connect('scans.db')
+    conn.row_factory = sqlite3.Row
+    c = conn.cursor()
+    
+    # Get output dir to cleanup
+    c.execute("SELECT output_dir FROM scans WHERE uuid = ?", (uuid,))
+    row = c.fetchone()
+    
+    if row and row['output_dir'] and os.path.exists(row['output_dir']):
+        import shutil
+        try:
+            shutil.rmtree(row['output_dir'])
+        except Exception as e:
+            print(f"Error deleting output dir: {e}")
+            
+    c.execute("DELETE FROM scan_results WHERE scan_id = ?", (uuid,))
+    c.execute("DELETE FROM scans WHERE uuid = ?", (uuid,))
+    conn.commit()
+    conn.close()
+    return jsonify({"status": "deleted"})
+
+@app.route('/scans/<uuid>/download', methods=['GET'])
+def download_scan_zip(uuid):
+    conn = sqlite3.connect('scans.db')
+    conn.row_factory = sqlite3.Row
+    c = conn.cursor()
+    c.execute("SELECT output_dir, name FROM scans WHERE uuid = ?", (uuid,))
+    row = c.fetchone()
+    conn.close()
+
+    if not row:
+        return jsonify({"error": "Scan not found"}), 404
+        
+    output_dir = row['output_dir']
+    scan_name = row['name'] or f"scan_{uuid[:8]}"
+    
+    if not output_dir:
+        return jsonify({"error": "No output directory for this scan"}), 404
+
+    # Ensure absolute path resolution
+    if not os.path.isabs(output_dir):
+        output_dir = os.path.join(os.getcwd(), output_dir)
+
+    if not os.path.exists(output_dir):
+        # Scan might have failed before creating dir, or it was deleted
+        return jsonify({"error": "Output directory not found on server"}), 404
+
+    # Create Zip in memory
+    memory_file = io.BytesIO()
+    with zipfile.ZipFile(memory_file, 'w', zipfile.ZIP_DEFLATED) as zf:
+        json_files = glob.glob(os.path.join(output_dir, "*_output.json"))
+        for f in json_files:
+             # Validate JSON
+            parsed = clean_and_parse_json(f)
+            # Only include if valid JSON and not an error object we created
+            if parsed and not (isinstance(parsed, dict) and "error" in parsed and parsed["error"] == "Invalid JSON output"):                 
+                 # Add to zip
+                 arcname = os.path.basename(f)
+                 zf.writestr(arcname, json.dumps(parsed, indent=2))
+
+    memory_file.seek(0)
+    return send_file(
+        memory_file,
+        mimetype='application/zip',
+        as_attachment=True,
+        download_name=f"{secure_filename(scan_name)}_results.zip"
+    )
+
+
+def clean_and_parse_json(filepath):
+    """Helper to parse JSON from Volatility output files, handling errors gracefully."""
+    try:
+        with open(filepath, 'r') as f:
+            content = f.read()
+            
+        start_index = content.find('[')
+        if start_index == -1:
+            start_index = content.find('{')
+        
+        parsed_data = None
+        if start_index != -1:
+            try:
+                json_content = content[start_index:]
+                parsed_data = json.loads(json_content)
+            except:
+                pass # Try fallback
+        
+        if parsed_data is None:
+             lines = content.splitlines()
+             if len(lines) > 1:
+                 try:
+                    parsed_data = json.loads('\n'.join(lines[1:]))
+                 except:
+                    pass
+        
+        if parsed_data is not None:
+            return parsed_data
+            
+        # Fallback: Return raw content as error object if not valid JSON
+        # This handles Volatility error messages stored in .json files
+        return {"error": "Invalid JSON output", "raw_output": content}
+
+    except Exception as e:
+        return {"error": f"Error reading file: {str(e)}"}
+
+def ingest_results_to_db(scan_id, output_dir):
+    """Reads JSON output files and stores them in the database."""
+    print(f"[DEBUG] Ingesting results for {scan_id} from {output_dir}")
+    if not os.path.exists(output_dir):
+         print(f"[ERROR] Output dir not found: {output_dir}")
+         return
+
+    conn = sqlite3.connect('scans.db')
+    c = conn.cursor()
+    
+    json_files = glob.glob(os.path.join(output_dir, "*_output.json"))
+    for f in json_files:
+        try:
+            filename = os.path.basename(f)
+            if filename.endswith("_output.json"):
+                module_name = filename[:-12]
+                
+                # Check if result already exists to avoid duplicates (idempotency)
+                c.execute("SELECT id FROM scan_results WHERE scan_id = ? AND module = ?", (scan_id, module_name))
+                if c.fetchone():
+                    continue
+                
+                # Parse or read content
+                parsed_data = clean_and_parse_json(f)
+                content_str = json.dumps(parsed_data) if parsed_data else "{}"
+                if parsed_data and "error" in parsed_data and parsed_data["error"] == "Invalid JSON output":
+                     # Store raw output if it was an error
+                     content_str = json.dumps(parsed_data)
+
+                c.execute("INSERT INTO scan_results (scan_id, module, content, created_at) VALUES (?, ?, ?, ?)",
+                          (scan_id, module_name, content_str, time.time()))
+        except Exception as e:
+            print(f"[ERROR] Failed to ingest {f}: {e}")
+            
+    conn.commit()
+    conn.close()
+    print(f"[DEBUG] Ingestion complete for {scan_id}")
+
+@app.route('/upload', methods=['POST'])
+def upload_file():
+    if 'file' not in request.files:
+        return jsonify({"error": "No file part"}), 400
+    file = request.files['file']
+    if file.filename == '':
+        return jsonify({"error": "No chosen file"}), 400
+    
+    if file:
+        filename = secure_filename(file.filename)
+        save_path = os.path.join(STORAGE_DIR, filename)
+        
+        # Check if file already exists to avoid overwrite or just overwrite?
+        # For simplicity, we overwrite.
+        try:
+            print(f"[DEBUG] Saving file to {save_path}")
+            file.save(save_path)
+            
+            # Calculate and cache hash immediately
+            print(f"[DEBUG] Calculating hash for {save_path}")
+            get_file_hash(save_path)
+            
+            print(f"[DEBUG] File saved successfully")
+            return jsonify({"status": "success", "path": save_path, "server_path": save_path})
+        except Exception as e:
+            print(f"[ERROR] Failed to save file: {e}")
+            return jsonify({"error": str(e)}), 500
+
+@app.route('/scan', methods=['POST'])
+def scan():
+    data = request.json
+    
+    # Define default arguments matching CLI defaults and requirements
+    default_args = {
+        "profiles_path": os.path.join(os.getcwd(), "volatility2_profiles"),
+        "symbols_path": os.path.join(os.getcwd(), "volatility3_symbols"),
+        "cache_path": os.path.join(os.getcwd(), "volatility3_cache"),
+        "plugins_dir": os.path.join(os.getcwd(), "volatility3_plugins"),
+        "format": "json",
+        "commands": None,
+        "light": False,
+        "full": False,
+        "linux": False,
+        "windows": False,
+        "mode": None,
+        "profile": None,
+        "processes": None,
+        "host_path": os.environ.get("HOST_PATH") # Added for DooD support via Env
+    }
+    
+    args_dict = default_args.copy()
+    args_dict.update(data)
+    
+    # Basic Validation
+    if "dump" not in data or "image" not in data or "mode" not in data:
+         return jsonify({"error": "Missing required fields: dump, image, mode"}), 400
+
+    # Ensure mutual exclusion for OS flags
+    is_linux = bool(data.get("linux"))
+    is_windows = bool(data.get("windows"))
+    
+    if is_linux == is_windows:
+        return jsonify({"error": "You must specify either 'linux': true or 'windows': true, but not both or neither."}), 400
+
+    args_obj = argparse.Namespace(**args_dict)
+    
+    scan_id = str(uuid.uuid4())
+    # Construct output directory with UUID
+    base_name = f"volatility2_{scan_id}" if args_obj.mode == "vol2" else f"volatility3_{scan_id}"
+    # Use absolute path for output_dir to avoid CWD ambiguity and ensure persistence
+    final_output_dir = os.path.join(os.getcwd(), "outputs", base_name)
+    args_obj.output_dir = final_output_dir
+    
+    # Ensure directory exists immediately (even if empty) to prevent "No output dir" errors on early failure
+    try:
+        os.makedirs(final_output_dir, exist_ok=True)
+    except Exception as e:
+        print(f"[ERROR] Failed to create output dir {final_output_dir}: {e}")
+        return jsonify({"error": f"Failed to create output directory: {e}"}), 500
+
+    # Determine OS and Volatility Version for DB
+    target_os = "windows" if args_obj.windows else ("linux" if args_obj.linux else "unknown")
+    vol_version = args_obj.mode
+
+    # Fix dump path if it's just a filename (assume it's in storage)
+    # If it's an absolute path (from previous configs), we trust it?
+    # Actually, we should force it to check /storage if it looks like a filename
+    if not os.path.isabs(args_obj.dump) and not args_obj.dump.startswith('/'):
+         args_obj.dump = os.path.join(STORAGE_DIR, args_obj.dump)
+
+    if not os.path.exists(args_obj.dump):
+        return jsonify({"error": f"Dump file not found at {args_obj.dump}"}), 400
+
+    args_obj.image = data.get("image") # Ensure image is passed
+    case_name = data.get("name") # Optional custom case name
+
+    conn = sqlite3.connect('scans.db')
+    c = conn.cursor()
+    c.execute("INSERT INTO scans (uuid, status, mode, os, volatility_version, dump_path, output_dir, created_at, image, name) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+              (scan_id, "pending", "light" if args_obj.light else "full", target_os, vol_version, args_obj.dump, final_output_dir, time.time(), args_obj.image, case_name))
+    conn.commit()
+    conn.close()
+
+    def background_scan(s_id, args):
+        conn = sqlite3.connect('scans.db')
+        c = conn.cursor()
+        
+        try:
+            c.execute("UPDATE scans SET status = 'running' WHERE uuid = ?", (s_id,))
+            conn.commit()
+            
+            # Execute the runner
+            if runner_func:
+                runner_func(args)
+            
+            # Ingest results to DB
+            ingest_results_to_db(s_id, args.output_dir)
+            
+            c.execute("UPDATE scans SET status = 'completed' WHERE uuid = ?", (s_id,))
+            conn.commit()
+        except Exception as e:
+            print(f"[ERROR] Scan failed: {e}")
+            c.execute("UPDATE scans SET status = 'failed', error = ? WHERE uuid = ?", (str(e), s_id))
+            conn.commit()
+        finally:
+            conn.close()
+
+    thread = threading.Thread(target=background_scan, args=(scan_id, args_obj))
+    thread.daemon = True
+    thread.start()
+
+    return jsonify({"scan_id": scan_id, "status": "pending", "output_dir": final_output_dir})
+
+@app.route('/status/<scan_id>', methods=['GET'])
+def get_status(scan_id):
+    conn = sqlite3.connect('scans.db')
+    conn.row_factory = sqlite3.Row
+    c = conn.cursor()
+    c.execute("SELECT * FROM scans WHERE uuid = ?", (scan_id,))
+    row = c.fetchone()
+    conn.close()
+    
+    if row:
+        return jsonify(dict(row))
+    return jsonify({"error": "Scan not found"}), 404
+
+@app.route('/list_images', methods=['GET'])
+def list_images():
+    try:
+        client = docker.from_env()
+        images = client.images.list()
+        volatility_images = []
+        for img in images:
+            if img.tags:
+                for tag in img.tags:
+                    if "volatility" in tag:
+                        volatility_images.append(tag)
+        return jsonify({"images": list(set(volatility_images))})
+    except Exception as e:
+        return jsonify({"error": str(e)}), 500
+
+@app.route('/results/<uuid>/modules', methods=['GET'])
+def get_scan_modules(uuid):
+    conn = sqlite3.connect('scans.db')
+    conn.row_factory = sqlite3.Row
+    c = conn.cursor()
+    
+    # Check if we have results in DB
+    c.execute("SELECT module, content FROM scan_results WHERE scan_id = ?", (uuid,))
+    rows = c.fetchall()
+    
+    if rows:
+        modules = []
+        for row in rows:
+            try:
+                # content is stored as JSON string
+                # We do a quick check to see if it's our known error structure
+                # Parsing huge JSONs just to check error might be slow, but safe
+                data = json.loads(row['content'])
+                if isinstance(data, dict) and data.get("error") == "Invalid JSON output":
+                    continue
+                modules.append(row['module'])
+            except:
+                continue
+        conn.close()
+        return jsonify({"modules": modules})
+    
+    # Fallback to filesystem if DB empty
+    c.execute("SELECT output_dir FROM scans WHERE uuid = ?", (uuid,))
+    scan = c.fetchone()
+    conn.close()
+    
+    if not scan:
+         return jsonify({"error": "Scan not found"}), 404
+    
+    output_dir = scan['output_dir']
+    if output_dir and os.path.exists(output_dir):
+        json_files = glob.glob(os.path.join(output_dir, "*_output.json"))
+        modules = []
+        for f in json_files:
+            filename = os.path.basename(f)
+            if filename.endswith("_output.json"):
+                # Validate content
+                parsed_data = clean_and_parse_json(f)
+                if parsed_data and isinstance(parsed_data, dict) and parsed_data.get("error") == "Invalid JSON output":
+                    continue
+                    
+                module_name = filename[:-12]
+                modules.append(module_name)
+        return jsonify({"modules": modules})
+        
+    return jsonify({"modules": []})
+
+@app.route('/results/<uuid>', methods=['GET'])
+def get_scan_results(uuid):
+    module_param = request.args.get('module')
+    if not module_param:
+        return jsonify({"error": "Missing 'module' query parameter"}), 400
+        
+    conn = sqlite3.connect('scans.db')
+    conn.row_factory = sqlite3.Row
+    c = conn.cursor()
+    
+    # try DB first
+    c.execute("SELECT content FROM scan_results WHERE scan_id = ? AND module = ?", (uuid, module_param))
+    row = c.fetchone()
+    if row:
+        conn.close()
+        try:
+            return jsonify(json.loads(row['content']))
+        except:
+            return jsonify({"error": "Failed to parse stored content", "raw": row['content']}), 500
+
+    # Fallback to filesystem
+    c.execute("SELECT output_dir FROM scans WHERE uuid = ?", (uuid,))
+    scan = c.fetchone()
+    conn.close()
+    
+    if not scan:
+         return jsonify({"error": "Scan not found"}), 404
+    
+    output_dir = scan['output_dir']
+    if not output_dir or not os.path.exists(output_dir):
+         return jsonify({"error": "Output directory not found"}), 404
+
+    if module_param == 'all':
+        results = {}
+        json_files = glob.glob(os.path.join(output_dir, "*_output.json"))
+        for f in json_files:
+            filename = os.path.basename(f)
+            if filename.endswith("_output.json"):
+                module_name = filename[:-12]
+                parsed_data = clean_and_parse_json(f)
+                if parsed_data is not None:
+                    results[module_name] = parsed_data
+        return jsonify(results)
+    else:
+        target_file = os.path.join(output_dir, f"{module_param}_output.json")
+        if not os.path.exists(target_file):
+            return jsonify({"error": f"Module {module_param} output not found"}), 404
+            
+        parsed_data = clean_and_parse_json(target_file)
+        if parsed_data is None:
+             return jsonify({"error": f"Failed to parse JSON for {module_param}"}), 500
+             
+        return jsonify(parsed_data)
+
+@app.route('/scans', methods=['GET'])
+def list_scans():
+    conn = sqlite3.connect('scans.db')
+    conn.row_factory = sqlite3.Row
+    c = conn.cursor()
+    c.execute("SELECT * FROM scans ORDER BY created_at DESC")
+    rows = c.fetchall()
+    
+    scans_list = []
+    for row in rows:
+        scan_dict = dict(row)
+        scan_uuid = scan_dict['uuid']
+        
+        # Count valid modules from DB (excluding known errors)
+        # We explicitly check for our known error string to filter out failed modules
+        c.execute("SELECT COUNT(*) FROM scan_results WHERE scan_id = ? AND content NOT LIKE '%\"error\": \"Invalid JSON output\"%'", (scan_uuid,))
+        db_count = c.fetchone()[0]
+        
+        scan_dict['modules'] = db_count
+        
+        # Override status to 'failed' if technically completed but 0 valid modules
+        if scan_dict['status'] == 'completed' and db_count == 0:
+            scan_dict['status'] = 'failed'
+            scan_dict['error'] = 'No valid JSON results parsed'
+
+        # Fallback to filesystem count (only if DB count is 0 and we want to be sure? 
+        # Actually DB is source of truth for results now. If ingest failed, it's failed.)
+        
+        scan_dict['findings'] = 0 
+        scans_list.append(scan_dict)
+
+
+    
+    conn.close()
+    return jsonify(scans_list)
+
+@app.route('/stats', methods=['GET'])
+def get_stats():
+    conn = sqlite3.connect('scans.db')
+    c = conn.cursor()
+    c.execute("SELECT COUNT(*) FROM scans")
+    total_cases = c.fetchone()[0]
+    
+    c.execute("SELECT COUNT(*) FROM scans WHERE status='running'")
+    running_cases = c.fetchone()[0]
+    
+    c.execute("SELECT COUNT(DISTINCT dump_path) FROM scans")
+    total_evidences = c.fetchone()[0]
+    
+    conn.close()
+    
+    # Count symbols
+    symbols_path = os.path.join(os.getcwd(), "volatility3_symbols")
+    total_symbols = 0
+    if os.path.exists(symbols_path):
+        for root, dirs, files in os.walk(symbols_path):
+            total_symbols += len(files)
+
+    return jsonify({
+        "total_cases": total_cases,
+        "processing": running_cases,
+        "total_evidences": total_evidences,
+        "total_symbols": total_symbols
+    })
+
+@app.route('/evidences', methods=['GET'])
+def list_evidences():
+    # Helper to calculate size recursively
+    def get_dir_size(start_path):
+        total_size = 0
+        for dirpath, dirnames, filenames in os.walk(start_path):
+            for f in filenames:
+                fp = os.path.join(dirpath, f)
+                total_size += os.path.getsize(fp)
+        return total_size
+
+    try:
+        items = os.listdir(STORAGE_DIR)
+        print(f"[DEBUG] list_evidences found {len(items)} items in {STORAGE_DIR}")
+        print(f"[DEBUG] Items: {items}")
+    except FileNotFoundError:
+        print(f"[ERROR] Storage dir not found: {STORAGE_DIR}")
+        items = []
+
+    # Pre-load Case Name map from DB
+    case_map = {} # filename -> case name
+    try:
+        conn = sqlite3.connect('scans.db')
+        conn.row_factory = sqlite3.Row
+        c = conn.cursor()
+        c.execute("SELECT name, dump_path FROM scans")
+        rows = c.fetchall()
+        for r in rows:
+            if r['name'] and r['dump_path']:
+                fname = os.path.basename(r['dump_path'])
+                case_map[fname] = r['name']
+        conn.close()
+    except:
+        pass
+
+    evidences = []
+    
+    # First pass: Identify extracted folders
+    processed_dumps = set()
+    extracted_map = {} # Unused but keeping for minimization if referenced elsewhere, though we will ignore it.
+
+    
+    for item in items:
+        path = os.path.join(STORAGE_DIR, item)
+        if os.path.isdir(path) and item.endswith("_extracted"):
+             # This is an extracted folder
+             dump_base = item[:-10] # remove _extracted
+             files = []
+             try:
+                  subitems = os.listdir(path)
+                  for sub in subitems:
+                      if sub.endswith('.sha256'):
+                          continue
+                      
+                      subpath = os.path.join(path, sub)
+                      if os.path.isfile(subpath):
+                         files.append({
+                             "id": os.path.join(item, sub), # Relative path ID for download
+                             "name": sub,
+                             "size": os.path.getsize(subpath),
+                             "type": "Extracted File"
+                         })
+             except Exception as e:
+                 print(f"Error reading subdir {path}: {e}")
+            
+             # Resolve Source Dump from DB using Folder Name matches
+             source_dump = "Unknown Source"
+             # 1. Check if dump_base matches a Case Name (Case Name Extraction)
+             # If so, source is the dump file associated with that case
+             # 2. Check if dump_base matches a Filename (Legacy Extraction)
+             
+             # Case Name match attempt
+             matched_case_name = dump_base
+             try:
+                 conn = sqlite3.connect('scans.db')
+                 conn.row_factory = sqlite3.Row
+                 c = conn.cursor()
+                 c.execute("SELECT dump_path FROM scans WHERE name = ? ORDER BY created_at DESC LIMIT 1", (dump_base,))
+                 row = c.fetchone()
+                 if row:
+                     source_dump = os.path.basename(row['dump_path'])
+                 else:
+                     source_dump = dump_base
+                 conn.close()
+             except:
+                 source_dump = dump_base
+
+             # If source dump exists in storage, add it to children list as requested
+             if source_dump and source_dump != "Unknown Source":
+                 dump_path = os.path.join(STORAGE_DIR, source_dump)
+                 if os.path.exists(dump_path):
+                     processed_dumps.add(source_dump)
+                     files.insert(0, {
+                         "id": source_dump, # Relative path (just filename)
+                         "name": source_dump,
+                         "size": os.path.getsize(dump_path),
+                         "type": "Memory Dump",
+                         "is_source": True
+                     })
+
+             evidences.append({
+                 "id": item,
+                 "name": matched_case_name, 
+                 "type": "Evidence Group",
+                 "size": get_dir_size(path),
+                 "hash": source_dump, 
+                 "source_id": source_dump if os.path.exists(os.path.join(STORAGE_DIR, source_dump)) else None, 
+                 "uploaded": "Extracted group",
+                 "children": files
+             })
+             
+    # Second pass: List main dumps and attach extracted files
+    for item in items:
+        path = os.path.join(STORAGE_DIR, item)
+        if os.path.isfile(path) and not item.endswith('.sha256'):
+            # It's a dump file (or other uploaded file)
+            # Skip if it's already included in an evidence group
+            if item in processed_dumps:
+                continue
+
+            # Resolve Display Name (Case Name)
+            display_name = case_map.get(item, item)
+            
+            # WRAP IN GROUP to ensure Folder Style
+            child_file = {
+                "id": item,
+                "name": item,
+                "size": os.path.getsize(path),
+                "type": "Memory Dump",
+                "hash": get_file_hash(path),
+                "uploaded": time.strftime('%Y-%m-%d', time.localtime(os.path.getmtime(path))),
+                "is_source": True
+            }
+            
+            evidences.append({
+                "id": f"group_{item}", # Virtual ID for the group
+                "name": display_name,
+                "size": os.path.getsize(path),
+                "type": "Evidence Group",
+                "hash": item, 
+                "source_id": item,
+                "uploaded": time.strftime('%Y-%m-%d', time.localtime(os.path.getmtime(path))),
+                "children": [child_file] 
+            })
+            
+    return jsonify(evidences)
+
+def calculate_sha256(filepath):
+    """Calculates SHA-256 hash of a file."""
+    sha256_hash = hashlib.sha256()
+    with open(filepath, "rb") as f:
+        for byte_block in iter(lambda: f.read(4096), b""):
+            sha256_hash.update(byte_block)
+    return sha256_hash.hexdigest()
+
+def get_file_hash(filepath):
+    """Gets cached hash or calculates it."""
+    hash_file = filepath + ".sha256"
+    if os.path.exists(hash_file):
+        try:
+            with open(hash_file, 'r') as f:
+                return f.read().strip()
+        except:
+            pass
+    
+    # Calculate and cache
+    try:
+        file_hash = calculate_sha256(filepath)
+        with open(hash_file, 'w') as f:
+            f.write(file_hash)
+        return file_hash
+    except Exception as e:
+        print(f"[ERROR] Failed to calc hash for {filepath}: {e}")
+        return "Error"
+
+
+
+@app.route('/evidence/<filename>', methods=['DELETE'])
+def delete_evidence(filename):
+    filename = secure_filename(filename)
+    path = os.path.join(STORAGE_DIR, filename)
+    if os.path.exists(path):
+        import shutil
+        try:
+            if os.path.isdir(path):
+                shutil.rmtree(path)
+            else:
+                os.remove(path)
+                # Remove sidecar hash if exists
+                if os.path.exists(path + ".sha256"):
+                     os.remove(path + ".sha256")
+                
+                # Also remove extracted directory (if this was a dump file)
+                # Checks for standard <filename>_extracted pattern
+                extracted_dir = os.path.join(STORAGE_DIR, f"{filename}_extracted")
+                if os.path.exists(extracted_dir):
+                    shutil.rmtree(extracted_dir)
+                
+            return jsonify({"status": "deleted"})
+        except Exception as e:
+            print(f"[ERROR] Failed to delete {path}: {e}")
+            return jsonify({"error": str(e)}), 500
+    return jsonify({"error": "File not found"}), 404
+
+@app.route('/evidence/<path:filename>/download', methods=['GET'])
+def download_evidence(filename):
+    # Allow nested paths for extracted files
+    # send_from_directory handles traversal attacks (mostly), but we shouldn't use secure_filename on the whole path
+    return send_from_directory(STORAGE_DIR, filename, as_attachment=True)
+
+
+def cleanup_timeouts():
+    """Marks scans running for > 1 hour as failed (timeout)."""
+    try:
+        conn = sqlite3.connect('scans.db')
+        c = conn.cursor()
+        one_hour_ago = time.time() - 3600
+        
+        # Find tasks that are 'running' and older than 1 hour
+        c.execute("SELECT uuid FROM scans WHERE status='running' AND created_at < ?", (one_hour_ago,))
+        stale_scans = c.fetchall()
+        
+        if stale_scans:
+            print(f"Cleaning up {len(stale_scans)} stale scans...")
+            c.execute("UPDATE scans SET status='failed', error='Timeout (>1h)' WHERE status='running' AND created_at < ?", (one_hour_ago,))
+            conn.commit()
+            
+        conn.close()
+    except Exception as e:
+        print(f"Error cleaning up timeouts: {e}")
+
+def background_dump_task(task_id, scan_id, virt_addr, docker_image):
+    """Background worker for extracting files from memory dump."""
+    conn = sqlite3.connect('scans.db')
+    c = conn.cursor()
+    c.row_factory = sqlite3.Row
+    
+    try:
+        c.execute("UPDATE dump_tasks SET status = 'running' WHERE task_id = ?", (task_id,))
+        conn.commit()
+        
+        # 1. Get Scan Details
+        c.execute("SELECT * FROM scans WHERE uuid = ?", (scan_id,))
+        scan = c.fetchone()
+        
+        if not scan:
+             raise Exception("Scan not found")
+             
+        dump_path = scan['dump_path']
+        if not os.path.isabs(dump_path) and not dump_path.startswith('/'):
+            dump_path = os.path.join(STORAGE_DIR, dump_path)
+            
+        # 2. Setup Output Paths
+        scan_output_dir = scan['output_dir']
+        # Ensure scan output dir exists
+        if not scan_output_dir or not os.path.exists(scan_output_dir):
+             scan_output_dir = os.path.join(os.getcwd(), "outputs", f"volatility3_{scan_id}")
+             os.makedirs(scan_output_dir, exist_ok=True)
+             
+        target_output_dir = os.path.join(scan_output_dir, "downloads", task_id)
+        os.makedirs(target_output_dir, exist_ok=True)
+        
+        # 3. Resolve Paths & Volumes
+        host_path = os.environ.get("HOST_PATH")
+        def resolve(p):
+            if host_path:
+                if p.startswith(os.getcwd()):
+                    rel = os.path.relpath(p, os.getcwd())
+                    return os.path.join(host_path, rel)
+                if p.startswith("/storage"):
+                     return os.path.join(host_path, "storage", "data", os.path.relpath(p, "/storage"))
+            return p
+
+        abs_dump_path = os.path.abspath(dump_path)
+        abs_dump_dir = os.path.dirname(abs_dump_path)
+        dump_filename = os.path.basename(abs_dump_path)
+
+        symbols_path = os.path.join(os.getcwd(), "volatility3_symbols")
+        cache_path = os.path.join(os.getcwd(), "volatility3_cache")
+        plugins_path = os.path.join(os.getcwd(), "volatility3_plugins")
+
+        volumes = {
+            resolve(abs_dump_dir): {'bind': '/dump_dir', 'mode': 'ro'},
+            resolve(target_output_dir): {'bind': '/output', 'mode': 'rw'},
+            resolve(symbols_path): {'bind': '/symbols', 'mode': 'rw'},
+            resolve(cache_path): {'bind': '/root/.cache/volatility3', 'mode': 'rw'},
+            resolve(plugins_path): {'bind': '/plugins', 'mode': 'ro'}
+        }
+
+        # 4. Run Docker Command
+        client = docker.from_env()
+        cmd = [
+            "vol", "-q", 
+            "-f", f"/dump_dir/{dump_filename}", 
+            "-o", "/output", 
+            "windows.dumpfiles.DumpFiles", 
+            "--virtaddr", str(virt_addr)
+        ]
+        
+        print(f"[DEBUG] [Task {task_id}] Running: {cmd}")
+        
+        client.containers.run(
+            image=docker_image,
+            command=cmd,
+            volumes=volumes,
+            remove=True,
+            stderr=True,
+            stdout=True
+        ) # This blocks until completion
+
+        # 5. Identify Result File
+        files = os.listdir(target_output_dir)
+        target_file = None
+
+        for f in files:
+            if not f.endswith(".json") and f != "." and f != "..":
+                target_file = f
+                break
+        
+        if not target_file:
+             raise Exception("No file extracted (DumpFiles returned no candidate)")
+
+        # Organize downloads in STORAGE_DIR / <CaseName_or_DumpName>_extracted / <target_file>
+        # Use Case Name if available, otherwise dump filename
+        case_name = scan['name']
+        if case_name:
+             # Sanitize case name for folder usage
+             safe_case_name = secure_filename(case_name)
+             extracted_dir_name = f"{safe_case_name}_extracted"
+        else:
+             extracted_dir_name = f"{dump_filename}_extracted"
+             
+        storage_extracted_dir = os.path.join(STORAGE_DIR, extracted_dir_name)
+        os.makedirs(storage_extracted_dir, exist_ok=True)
+        
+        final_path = os.path.join(storage_extracted_dir, target_file)
+        
+        # Move from temp output to final storage
+        import shutil
+        shutil.move(os.path.join(target_output_dir, target_file), final_path)
+        
+        # 6. Mark Completed
+        c.execute("UPDATE dump_tasks SET status = 'completed', output_path = ? WHERE task_id = ?", (final_path, task_id))
+        conn.commit()
+        print(f"[DEBUG] [Task {task_id}] Completed. Moved to: {final_path}")
+
+    except Exception as e:
+        print(f"[ERROR] [Task {task_id}] Failed: {e}")
+        c.execute("UPDATE dump_tasks SET status = 'failed', error = ? WHERE task_id = ?", (str(e), task_id))
+        conn.commit()
+    finally:
+        conn.close()
+
+@app.route('/scan/<scan_id>/dump-file', methods=['POST'])
+def dump_file_from_memory(scan_id):
+    data = request.json
+    virt_addr = data.get('virt_addr')
+    docker_image = data.get('image')
+    
+    if not virt_addr:
+        return jsonify({"error": "Missing 'virt_addr'"}), 400
+    if not docker_image:
+        return jsonify({"error": "Missing 'image'"}), 400
+
+    conn = sqlite3.connect('scans.db')
+    conn.row_factory = sqlite3.Row
+    c = conn.cursor()
+    c.execute("SELECT * FROM scans WHERE uuid = ?", (scan_id,))
+    scan = c.fetchone()
+    
+    if not scan:
+        conn.close()
+        return jsonify({"error": "Scan not found"}), 404
+
+    # Create Task
+    task_id = str(uuid.uuid4())
+    c.execute("INSERT INTO dump_tasks (task_id, scan_id, status, created_at) VALUES (?, ?, ?, ?)",
+              (task_id, scan_id, "pending", time.time()))
+    conn.commit()
+    conn.close()
+    
+    # Start Background Thread
+    thread = threading.Thread(target=background_dump_task, args=(task_id, scan_id, virt_addr, docker_image))
+    thread.daemon = True
+    thread.start()
+    
+    return jsonify({"task_id": task_id, "status": "pending"})
+
+@app.route('/dump-task/<task_id>', methods=['GET'])
+def get_dump_status(task_id):
+    conn = sqlite3.connect('scans.db')
+    conn.row_factory = sqlite3.Row
+    c = conn.cursor()
+    c.execute("SELECT * FROM dump_tasks WHERE task_id = ?", (task_id,))
+    task = c.fetchone()
+    conn.close()
+    
+    if not task:
+        return jsonify({"error": "Task not found"}), 404
+        
+    return jsonify(dict(task))
+
+@app.route('/dump-task/<task_id>/download', methods=['GET'])
+def download_dump_result(task_id):
+    conn = sqlite3.connect('scans.db')
+    conn.row_factory = sqlite3.Row
+    c = conn.cursor()
+    c.execute("SELECT * FROM dump_tasks WHERE task_id = ?", (task_id,))
+    task = c.fetchone()
+    conn.close()
+    
+    if not task:
+        return jsonify({"error": "Task not found"}), 404
+        
+    if task['status'] != 'completed':
+        return jsonify({"error": "Task not completed"}), 400
+        
+    file_path = task['output_path']
+    if not file_path or not os.path.exists(file_path):
+        return jsonify({"error": "File not found on server"}), 404
+        
+    return send_file(
+        file_path,
+        as_attachment=True,
+        download_name=os.path.basename(file_path)
+    )
+
+def run_api(runner_cb, debug_mode=False):
+    global runner_func
+    runner_func = runner_cb
+    cleanup_timeouts() # Clean up stale tasks on startup
+    app.run(host='0.0.0.0', port=5001, debug=debug_mode)
+