🔍 Zizy — Forensic IOC Extraction Tool

Zizy is a command-line forensic tool for security analysts. Point it at any log file or artifact and it automatically extracts Indicators of Compromise (IOCs), optionally checks them against VirusTotal, and generates a timestamped PDF report — in English or Japanese.

---

✨ Features

Feature	Details
IOC Extraction	IPs, domains, URLs, MD5/SHA-1/SHA-256/SHA-512 hashes, Windows & Unix file paths
Smart Base64 Decoder	Decodes Base64 blobs only when they contain suspicious keywords (powershell, invoke, IEX, downloadstring, etc.)
VirusTotal Integration	Interactive VT reputation lookup with secure API key prompt
Domain Whitelist	Built-in whitelist filters common safe domains to reduce noise
Console Table	ANSI colour-coded summary table (red = malicious, yellow = suspicious, green = clean)
PDF Report	Formal, timestamped forensic PDF with IOC summary and per-artifact verdicts
Bilingual UI	Full English 🇬🇧 and Japanese 🇯🇵 interface support

---

📋 Requirements

• Python 3.8+
• reportlab — PDF generation

pip install -r requirements.txt

---

🚀 Quick Start

# Clone
git clone https://github.com/YOUR_USERNAME/zizy.git
cd zizy

# Install dependencies
pip install -r requirements.txt

# Run a scan (language picker appears)
python zizy.py /var/log/auth.log

# Specify language explicitly
python zizy.py suspicious.log --lang en

# Japanese UI
python zizy.py suspect.log --lang ja

# Skip VirusTotal, custom report output
python zizy.py access.log --lang en --no-vt --output my_report.pdf

---

🖥️ Usage

usage: zizy [-h] [--lang {en,ja}] [--output OUTPUT] [--no-vt] logfile

Zizy – Forensic IOC Extraction Tool

positional arguments:
  logfile               Path to the log/artifact file to scan

optional arguments:
  -h, --help            show this help message and exit
  --lang {en,ja}        Interface language (en/ja). If omitted, prompts on startup.
  --output OUTPUT, -o OUTPUT
                        PDF report output path (default: zizy_report_<timestamp>.pdf)
  --no-vt               Skip VirusTotal reputation check

---

📂 What Gets Extracted

IOC Types

Type	Pattern	Example
IPv4 Address	RFC-compliant regex	185.220.101.47
Domain	Known TLD list	evilpayload.onion
URL	HTTP/HTTPS	http://c2.xyz/payload.exe
MD5 Hash	32 hex chars	44d88612fea8a8f36de82e1278abb02f
SHA-1 Hash	40 hex chars	da39a3ee5e6b4b0d3255bfef95601890afd80709
SHA-256 Hash	64 hex chars	e3b0c44298fc1c149afbf4c8996fb924...
SHA-512 Hash	128 hex chars	full hash
Windows Path	C:\...	C:\Users\victim\AppData\svchost.exe
Unix Path	/...	/etc/passwd, /home/user/.ssh/id_rsa
Base64 (suspicious)	Keyword-filtered decode	powershell -encodedcommand IEX ...

Suspicious Base64 Keywords

Zizy only flags Base64 strings whose decoded content contains at least one of:

powershell  invoke  invoke-expression  iex  downloadstring
webclient   http    cmd.exe            base64  encode  decode
bypass      hidden  shellcode          payload exec    eval
rundll      regsvr  wscript            cscript mshta   certutil

---

🛡️ Domain Whitelist

Common safe domains are automatically excluded:

google.com  microsoft.com  apple.com  amazon.com  cloudflare.com
github.com  mozilla.org    ubuntu.com debian.org  w3.org  iana.org
... and more

To extend the whitelist, edit DOMAIN_WHITELIST in zizy.py.

---

🔬 VirusTotal Integration

When prompted, Zizy checks:

• IP addresses → /api/v3/ip_addresses/{ip}
• Domains → /api/v3/domains/{domain}
• URLs → /api/v3/urls/{url_id} (base64url encoded)
• File hashes → /api/v3/files/{hash}

The API key is entered via getpass and is never echoed to the terminal or written to disk.

Rate limiting: The free VT API allows 4 requests/minute. Zizy automatically pauses 15 seconds every 4 requests.

---

📄 Sample Output

Console

──────────────────────────────────────────────────────────────────────
  IP Addresses
──────────────────────────────────────────────────────────────────────
| Artifact          | VT Score | Verdict   |
| 185.220.101.47    | 12/94    | MALICIOUS |
| 192.168.1.105     | 0/94     | Clean     |

──────────────────────────────────────────────────────────────────────
  Decoded Base64 Strings
──────────────────────────────────────────────────────────────────────
| Encoded (truncated)       | Decoded (truncated)                      |
| cG93ZXJzaGVsbCAt…         | powershell -encodedcommand IEX (New-Ob…  |

PDF Report

The generated PDF includes:

• Report header with timestamp and target file path
• IOC category summary table with counts
• Per-category artifact tables with VirusTotal scores
• Colour-coded verdict rows (red / yellow / green)

---

🗂️ Project Structure

zizy/
├── zizy.py              # Main tool (single-file, no submodule dependencies)
├── requirements.txt     # Python dependencies
├── README.md            # This file
├── CHANGELOG.md         # Version history
├── CONTRIBUTING.md      # Contribution guidelines
├── LICENSE              # MIT License
├── .gitignore           # Git ignore rules
├── .github/
│   └── workflows/
│       └── ci.yml       # GitHub Actions CI
└── tests/
    ├── sample_log.txt   # Sample malicious log for testing
    └── test_zizy.py     # Unit tests

---

🧪 Running Tests

python -m pytest tests/ -v

---

🤝 Contributing

See CONTRIBUTING.md for guidelines on submitting issues and pull requests.

---

📝 Changelog

See CHANGELOG.md.

---

⚖️ License

This project is licensed under the MIT License — see LICENSE for details.

---

⚠️ Disclaimer

Zizy is intended for authorized security investigations only. The authors are not responsible for misuse. Always obtain proper authorization before scanning systems or files you do not own.