Encoded Command Analyzer

Overview

Encoded Command Analyzer is a Python-based detection engineering utility for decoding and analyzing encoded command-line content.

The tool is designed to help security analysts and detection engineers triage suspicious commands, identify signs of PowerShell abuse, detect common obfuscation patterns, map findings to MITRE ATT&CK techniques, suggest related detection rule ideas, generate starter Sigma and Microsoft Sentinel KQL templates, summarize detection coverage, and produce analyst-friendly investigation reports.

This project started as a simple Base64 decoder and has expanded into a lightweight encoded command analysis tool with CLI support, GUI support, batch file analysis, chained decoding, compressed Base64 support, XOR Hex decoding, suspicious keyword detection, configurable keyword rules, risk scoring, MITRE ATT&CK mapping, detection rule mapping, detection template generation, detection coverage summaries, analyst-ready exports, unit testing, Windows executable packaging, HTML report generation, and optional case context enrichment.

---

Current Version

Version 25

Current Capabilities

• Decode standard Base64 strings
• Decode PowerShell UTF-16LE EncodedCommand values
• Decode URL-encoded strings
• Decode Hex-encoded strings
• Decode chained encoding patterns
• Decode Gzip-compressed Base64
• Decode Deflate-compressed Base64
• Decode Raw Deflate Base64
• Decode single-byte XOR Hex strings
• Rank XOR Hex candidates and return the highest-confidence result
• Analyze a single encoded string
• Analyze a batch file containing multiple encoded strings
• Identify suspicious command-line keywords
• Load suspicious keyword rules from a JSON config file
• Use fallback default keyword rules if the config file is missing or invalid
• Assign a risk level based on detected indicators
• Explain why a command may be suspicious
• Map suspicious indicators to MITRE ATT&CK techniques
• Suggest related detection rule ideas
• Identify possible log sources for detection engineering
• Generate starter Sigma detection templates
• Generate starter Microsoft Sentinel KQL detection templates
• Generate a detection coverage summary
• Summarize MITRE ATT&CK techniques across all decoded results
• Summarize detection rule ideas across all decoded results
• Summarize Sigma and Sentinel templates across all decoded results
• Add optional case context to investigation results
• Add optional analyst notes to exported reports
• Export analysis results to JSON
• Export analysis results to CSV
• Export analyst triage reports to Markdown and HTML
• Generate dark-themed browser-based investigation reports
• Provide both CLI and Tkinter GUI interfaces
• Display a GUI risk banner for quick analyst review
• Unit tests for decoder logic
• Unit tests for detection logic
• Unit tests for risk scoring
• Unit tests for MITRE ATT&CK mapping
• Package the Tkinter GUI as a Windows executable
• Run the GUI without launching Python manually
• Distribute the executable through GitHub Releases

---

Why This Project Exists

Encoded and obfuscated commands are commonly seen during security investigations involving:

• Suspicious PowerShell execution
• EncodedCommand abuse
• Script-based payload delivery
• Command-line obfuscation
• Malware staging
• Initial access activity
• Execution and defense evasion activity
• SIEM and EDR alert investigation
• Compressed payload delivery
• Chained encoding and obfuscation
• Lightweight XOR-obfuscated strings

This tool provides a simple way to decode suspicious content and quickly review indicators that may be useful during triage, detection engineering, and incident response.

---

Supported Decoding

Encoding Type	Status
Base64 UTF-8	Supported
PowerShell UTF-16LE Base64	Supported
URL Encoding	Supported
Hex Encoding	Supported
Chained Encoding	Supported
Gzip Base64	Supported
Deflate Base64	Supported
Raw Deflate Base64	Supported
XOR Hex	Supported

---

Case Context Enrichment

The tool supports optional analyst case context fields.

Case context is not shown by default. It only appears in the console and exported reports when explicitly provided through CLI arguments.

Supported case fields:

Field	CLI Argument
Case ID	--case-id
Analyst Name	--analyst
Alert Source	--alert-source
Hostname	--hostname
Username	--username
Analyst Notes	--notes

Example:

python base64_decoder.py --input "cG93ZXJzaGVsbCUyRWV4ZSUyMC1lbmMlMjBJRVg=" --export --case-id "INC-1001" --analyst "SOC Analyst" --alert-source "Microsoft Defender" --hostname "WIN-TEST01" --username "test.user" --notes "Suspicious encoded PowerShell observed in process command line."

The case context is included in:

output/analysis_result.json
output/analysis_result.csv
output/triage_report.md
output/triage_report.html

For public examples, use generic values such as SOC Analyst or Analyst Name.

---

Configurable Keyword Rules

The tool supports configurable keyword rules.

Suspicious keyword logic can be managed in:

config/keyword_rules.json

This allows analysts and detection engineers to tune keywords, scores, severities, and reasons without editing the Python detection engine directly.

Example rule:

{
  "keyword": "iex",
  "severity": "High",
  "score": 3,
  "reason": "iex is commonly used in malicious or obfuscated script execution."
}

Each keyword rule can include:

Field	Purpose
keyword	The keyword or string to search for
severity	Analyst-friendly severity label
score	Numeric score added to the risk calculation
reason	Explanation shown in the output and reports

If the config file is missing, empty, or invalid, the tool falls back to built-in default keyword rules.

---

MITRE ATT&CK Mapping

The tool maps suspicious keyword matches to MITRE ATT&CK techniques.

Keyword / Indicator	MITRE Technique	Tactic
powershell	T1059.001 - PowerShell	Execution
iex	T1059.001 - PowerShell	Execution
invoke-expression	T1059.001 - PowerShell	Execution
cmd.exe	T1059.003 - Windows Command Shell	Execution
wscript	T1059.005 - Visual Basic	Execution
cscript	T1059.005 - Visual Basic	Execution
-enc	T1027 - Obfuscated Files or Information	Defense Evasion
-encodedcommand	T1027 - Obfuscated Files or Information	Defense Evasion
frombase64string	T1027 - Obfuscated Files or Information	Defense Evasion
bypass	T1562.001 - Disable or Modify Tools	Defense Evasion
hidden	T1564.003 - Hidden Window	Defense Evasion
downloadstring	T1105 - Ingress Tool Transfer	Command and Control
webclient	T1105 - Ingress Tool Transfer	Command and Control
http	T1105 - Ingress Tool Transfer	Command and Control
https	T1105 - Ingress Tool Transfer	Command and Control

MITRE mappings are based on keyword indicators and should be reviewed in context by an analyst.

---

Detection Rule Mapping

The tool suggests related detection ideas based on suspicious keywords found in the decoded command. This helps connect decoded artifacts to practical detection engineering opportunities.

Example decoded command:

powershell.exe -enc IEX

Example detection rule mappings:

Suspicious PowerShell EncodedCommand Execution
PowerShell Invoke-Expression Usage

Each detection mapping can include:

• Rule name
• Description
• Suggested severity
• Possible log sources
• Detection reason

Current Detection Rule Ideas

Detection Rule	Severity	Example Log Sources
Suspicious PowerShell EncodedCommand Execution	High	Microsoft Defender DeviceProcessEvents, Sysmon Event ID 1, Windows Security Event ID 4688
PowerShell Invoke-Expression Usage	Medium	Microsoft Defender DeviceProcessEvents, PowerShell Script Block Logs, Sysmon Event ID 1
PowerShell Remote Download Cradle	High	PowerShell Script Block Logs, Microsoft Defender DeviceProcessEvents, Proxy or Web Gateway Logs
Base64 Decoding Inside Script Content	Medium	PowerShell Script Block Logs, Microsoft Defender DeviceProcessEvents
Hidden PowerShell Window Execution	Medium	Microsoft Defender DeviceProcessEvents, Sysmon Event ID 1, Windows Security Event ID 4688
Windows Script Host Execution	Medium	Microsoft Defender DeviceProcessEvents, Sysmon Event ID 1, Windows Security Event ID 4688
Command Shell Execution	Low	Microsoft Defender DeviceProcessEvents, Sysmon Event ID 1, Windows Security Event ID 4688

Detection rule mappings are suggestions and should be tuned for the target environment.

---

Detection Templates

The tool can generate starter detection templates.

When suspicious decoded content matches known patterns, the tool can suggest starter detection templates such as:

• Sigma rules
• Microsoft Sentinel KQL queries

Example decoded command:

powershell.exe -enc IEX

Example generated templates:

Sigma: Suspicious PowerShell EncodedCommand
Microsoft Sentinel KQL: PowerShell EncodedCommand Execution
Microsoft Sentinel KQL: PowerShell Invoke-Expression Usage

Detection templates may include:

• Template name
• Template type
• Severity
• Description
• Query or rule body

These templates are intended as starting points and should be reviewed, tested, and tuned before production use.

---

Detection Coverage Summary

Version 25 adds a detection coverage summary.

The coverage summary aggregates key detection engineering outputs across all analysis results.

It summarizes:

• MITRE ATT&CK techniques identified
• Detection rule ideas suggested
• Detection templates generated

Example coverage summary:

Detection Coverage Summary
------------------------------------
MITRE Techniques Covered:
- T1059.001 - PowerShell
- T1027 - Obfuscated Files or Information

Detection Rule Ideas:
- Suspicious PowerShell EncodedCommand Execution
- PowerShell Invoke-Expression Usage

Detection Templates:
- Sigma: Suspicious PowerShell EncodedCommand
- Microsoft Sentinel KQL: PowerShell EncodedCommand Execution
- Microsoft Sentinel KQL: PowerShell Invoke-Expression Usage

The coverage summary appears in:

CLI output
output/triage_report.md
output/triage_report.html

This helps analysts quickly understand which behaviors, ATT&CK techniques, and detection opportunities were identified during analysis.

---

Suspicious Keyword Detection

The tool checks decoded content for suspicious or investigation-relevant keywords.

Default examples include:

powershell
-enc
-encodedcommand
iex
invoke-expression
downloadstring
frombase64string
webclient
start-process
cmd.exe
http
https
bypass
hidden
nop
wscript
cscript

Finding one of these keywords does not automatically mean the command is malicious. The results should be reviewed in context by an analyst.

Keyword behavior can be customized in:

config/keyword_rules.json

---

Risk Scoring

The tool assigns a risk level based on matched keyword rule scores.

Risk Level	Score Range	Meaning
None	0	No suspicious keywords found
Low	1-2	Minor suspicious indicators or useful investigation context
Medium	3-5	Suspicious command-line or PowerShell behavior
High	6+	Strong indicators of obfuscation, script execution, or payload activity

Example decoded command:

powershell.exe -enc IEX

This may be scored as High because it contains PowerShell execution, encoded command usage, and IEX.

---

XOR Hex Decoding

The tool supports single-byte XOR Hex decoding.

It can brute-force possible XOR keys, score decoded candidates, and return the highest-confidence result.

Example XOR Hex input:

534c544651504b464f4f0d465b46030e464d40036a667b

Expected decoded output:

powershell.exe -enc IEX

Example result:

Detected Encoding: XOR Hex Key 0x23
Risk Level: High
MITRE ATT&CK Mapping:
- T1059.001 - PowerShell
- T1027 - Obfuscated Files or Information

Detection Rule Mapping:
- Suspicious PowerShell EncodedCommand Execution
- PowerShell Invoke-Expression Usage

Detection Templates:
- Sigma: Suspicious PowerShell EncodedCommand
- Microsoft Sentinel KQL: PowerShell EncodedCommand Execution
- Microsoft Sentinel KQL: PowerShell Invoke-Expression Usage

XOR Hex detection is confidence-based and intended to help analysts identify suspicious strings during triage.

---

GUI Interface

The project includes a Tkinter-based GUI that allows analysts to:

• Paste encoded command content
• Analyze a single input
• Load a batch file
• Review decoded output
• Review suspicious keyword matches
• View risk score and reasons
• Review MITRE ATT&CK mappings
• Review detection rule mappings
• Review detection templates
• Export results to JSON, CSV, Markdown, and HTML
• Clear and rerun analysis

The GUI includes a color-coded risk banner:

Risk Level	Banner Meaning
High	Strong suspicious indicators detected
Medium	Suspicious behavior detected
Low	Minor indicators detected
None	No suspicious keywords detected

---

CLI Interface

The project supports command-line arguments for automation-friendly usage.

Analyze a Single Input

python base64_decoder.py --input "SGVsbG8gd29ybGQ="

Analyze Suspicious Chained Input

python base64_decoder.py --input "cG93ZXJzaGVsbCUyRWV4ZSUyMC1lbmMlMjBJRVg="

Analyze XOR Hex Input

python base64_decoder.py --input "534c544651504b464f4f0d465b46030e464d40036a667b"

Analyze with Optional Case Context

python base64_decoder.py --input "cG93ZXJzaGVsbCUyRWV4ZSUyMC1lbmMlMjBJRVg=" --export --case-id "INC-1001" --analyst "SOC Analyst" --alert-source "Microsoft Defender" --hostname "WIN-TEST01" --username "test.user" --notes "Suspicious encoded PowerShell observed in process command line."

Analyze a Batch File

python base64_decoder.py --file samples\sample_batch.txt

Analyze and Export Results

python base64_decoder.py --file samples\sample_batch.txt --export

Launch the GUI

python base64_decoder.py --gui

---

Project Structure

encoded-command-analyzer/
│
├── base64_decoder.py
├── encoded_command_gui.py
├── decoder_engine.py
├── detection_engine.py
├── report_exporter.py
├── config/
│   └── keyword_rules.json
├── samples/
│   └── sample_batch.txt
├── tests/
│   ├── test_decoder_engine.py
│   └── test_detection_engine.py
├── output/
│   ├── analysis_result.json
│   ├── analysis_result.csv
│   ├── triage_report.md
│   └── triage_report.html
├── README.md
├── LICENSE
└── .gitignore

Build artifacts such as build/, dist/, and *.spec are intentionally excluded from source control.

File Purpose

File	Purpose
base64_decoder.py	CLI entry point and command-line argument handler
encoded_command_gui.py	Tkinter GUI entry point
decoder_engine.py	Decoding logic for Base64, UTF-16LE, URL, Hex, chained decoding, compressed Base64, and XOR Hex
detection_engine.py	Suspicious keyword detection, configurable keyword loading, risk scoring, analysis logic, MITRE ATT&CK mapping, detection rule mapping, and detection template mapping
report_exporter.py	JSON, CSV, Markdown, and HTML export functions
config/keyword_rules.json	Configurable suspicious keyword rules
samples/	Sample input files for testing
tests/	Unit tests for decoder and detection logic
output/	Stores exported analysis results and triage reports

---

Requirements

This project currently uses Python standard libraries only.

No external packages are required for the analyzer itself.

Tested with:

Python 3.x

For Windows executable packaging, PyInstaller is required:

pip install pyinstaller

---

Testing

This project includes unit tests for the decoder and detection engines.

The tests validate:

• Base64 decoding
• PowerShell UTF-16LE decoding
• URL decoding
• Hex decoding
• Chained decoding
• Gzip Base64 decoding
• XOR Hex decoding
• Suspicious keyword detection
• Risk scoring
• MITRE ATT&CK mapping

Run all tests from the project root:

python -m unittest discover -s tests

Expected result:

OK

Test files are located in:

tests/
├── test_decoder_engine.py
└── test_detection_engine.py

---

Usage

Run the CLI Version

From the project folder:

python base64_decoder.py --input "SGVsbG8gd29ybGQ="

Run the GUI Version

From the project folder:

python encoded_command_gui.py

Or launch the GUI from the CLI:

python base64_decoder.py --gui

---

Windows Executable Packaging

The project supports packaging the Tkinter GUI as a Windows executable using PyInstaller.

Install PyInstaller:

pip install pyinstaller

Build the executable:

pyinstaller --onefile --windowed --name EncodedCommandAnalyzer encoded_command_gui.py

The executable will be created here:

dist/EncodedCommandAnalyzer.exe

Run the executable:

.\dist\EncodedCommandAnalyzer.exe

Packaging Notes

The following PyInstaller build artifacts are ignored by Git:

build/
dist/
*.spec

The executable should not be committed directly to the repository. Use GitHub Releases to distribute packaged builds.

---

Example: Clean Base64 Input

Input:

SGVsbG8gd29ybGQ=

Decoded output:

Hello world

Expected result:

Risk Level: None
Score: 0
No suspicious keywords found.

---

Example: PowerShell UTF-16LE EncodedCommand Input

Input:

cABvAHcAZQByAHMAaABlAGwAbAAuAGUAeABlACAALQBlAG4AYwAgAEkARQBYAA==

Decoded output:

powershell.exe -enc IEX

Example result:

Suspicious keywords found:
- powershell
- -enc
- iex

Risk Level: High
Score: 7

MITRE ATT&CK Mapping:
- T1059.001 - PowerShell
- T1027 - Obfuscated Files or Information

Detection Rule Mapping:
- Suspicious PowerShell EncodedCommand Execution
- PowerShell Invoke-Expression Usage

Detection Templates:
- Sigma: Suspicious PowerShell EncodedCommand
- Microsoft Sentinel KQL: PowerShell EncodedCommand Execution
- Microsoft Sentinel KQL: PowerShell Invoke-Expression Usage

Detection Coverage Summary:
- T1059.001 - PowerShell
- T1027 - Obfuscated Files or Information

---

Example: URL-Encoded Input

Input:

powershell%2Eexe%20-enc%20IEX

Decoded output:

powershell.exe -enc IEX

Example result:

Risk Level: High
MITRE ATT&CK Mapping:
- T1059.001 - PowerShell
- T1027 - Obfuscated Files or Information

Detection Rule Mapping:
- Suspicious PowerShell EncodedCommand Execution
- PowerShell Invoke-Expression Usage

Detection Templates:
- Sigma: Suspicious PowerShell EncodedCommand
- Microsoft Sentinel KQL: PowerShell EncodedCommand Execution
- Microsoft Sentinel KQL: PowerShell Invoke-Expression Usage

---

Example: Hex-Encoded Input

Input:

706f7765727368656c6c2e657865202d656e6320494558

Decoded output:

powershell.exe -enc IEX

Example result:

Risk Level: High
MITRE ATT&CK Mapping:
- T1059.001 - PowerShell
- T1027 - Obfuscated Files or Information

Detection Rule Mapping:
- Suspicious PowerShell EncodedCommand Execution
- PowerShell Invoke-Expression Usage

Detection Templates:
- Sigma: Suspicious PowerShell EncodedCommand
- Microsoft Sentinel KQL: PowerShell EncodedCommand Execution
- Microsoft Sentinel KQL: PowerShell Invoke-Expression Usage

---

Example: Chained Encoding

Input:

cG93ZXJzaGVsbCUyRWV4ZSUyMC1lbmMlMjBJRVg=

Decode flow:

Level 1: Base64 UTF-8
powershell%2Eexe%20-enc%20IEX

Level 2: URL
powershell.exe -enc IEX

Example final result:

Risk Level: High
Score: 7

MITRE ATT&CK Mapping:
- T1059.001 - PowerShell
- T1027 - Obfuscated Files or Information

Detection Rule Mapping:
- Suspicious PowerShell EncodedCommand Execution
- PowerShell Invoke-Expression Usage

Detection Templates:
- Sigma: Suspicious PowerShell EncodedCommand
- Microsoft Sentinel KQL: PowerShell EncodedCommand Execution
- Microsoft Sentinel KQL: PowerShell Invoke-Expression Usage

---

Example: Gzip Base64 Input

You can generate a Gzip Base64 test string with Python:

import base64
import gzip

text = "powershell.exe -enc IEX"

compressed = gzip.compress(text.encode("utf-8"))
encoded = base64.b64encode(compressed).decode("utf-8")

print(encoded)

Then analyze it:

python base64_decoder.py --input "PASTE_GZIP_BASE64_HERE"

Expected result:

Detected Encoding: Gzip Base64
Decoded Output:
powershell.exe -enc IEX

Risk Level: High

---

Example: XOR Hex Input

Input:

534c544651504b464f4f0d465b46030e464d40036a667b

Decoded output:

powershell.exe -enc IEX

Example result:

Detected Encoding: XOR Hex Key 0x23
Risk Level: High
MITRE ATT&CK Mapping:
- T1059.001 - PowerShell
- T1027 - Obfuscated Files or Information

Detection Rule Mapping:
- Suspicious PowerShell EncodedCommand Execution
- PowerShell Invoke-Expression Usage

Detection Templates:
- Sigma: Suspicious PowerShell EncodedCommand
- Microsoft Sentinel KQL: PowerShell EncodedCommand Execution
- Microsoft Sentinel KQL: PowerShell Invoke-Expression Usage

---

Example: Batch File Analysis

Create a text file with one encoded value per line:

SGVsbG8gd29ybGQ=
cABvAHcAZQByAHMAaABlAGwAbAAuAGUAeABlACAALQBlAG4AYwAgAEkARQBYAA==
powershell%2Eexe%20-enc%20IEX
706f7765727368656c6c2e657865202d656e6320494558
cG93ZXJzaGVsbCUyRWV4ZSUyMC1lbmMlMjBJRVg=
534c544651504b464f4f0d465b46030e464d40036a667b

Run:

python base64_decoder.py --file samples\sample_batch.txt

Optional export:

python base64_decoder.py --file samples\sample_batch.txt --export

---

Exporting Results

The tool can export results to:

output/analysis_result.json
output/analysis_result.csv
output/triage_report.md
output/triage_report.html

Exported fields include:

• Timestamp
• Case ID
• Analyst
• Alert Source
• Hostname
• Username
• Analyst Notes
• Batch item
• Source file
• Original input
• Detected encoding
• Decode level
• Source encoding
• Decoded text
• Suspicious keywords
• Risk level
• Risk score
• Risk reasons
• MITRE ATT&CK mappings
• Detection rule mappings
• Detection templates
• Detection coverage summary in Markdown and HTML reports

---

Analyst Triage Report

The generated Markdown triage report includes:

• Summary
• Optional case context
• Detection coverage summary
• Total results
• Highest risk level
• Highest score
• Original input
• Decoded output
• Suspicious keyword matches
• Risk score
• Risk reasons
• MITRE ATT&CK mappings
• Detection rule mappings
• Detection templates

The report is saved to:

output/triage_report.md

---

HTML Triage Report

The generated HTML report includes:

• Executive-style summary
• Optional case context
• Detection coverage summary
• Highest risk level
• Total result count
• Finding-by-finding breakdown
• Original input
• Decoded output
• Suspicious keyword matches
• Risk score and reasons
• MITRE ATT&CK mappings
• Detection rule mappings
• Detection templates
• Dark-themed browser-friendly formatting

The report is saved to:

output/triage_report.html

Open it from PowerShell:

start output\triage_report.html

---

Analyst Workflow

1. Copy suspicious encoded command from an alert.
2. Open Encoded Command Analyzer.
3. Paste the encoded value or load a batch file.
4. Add optional case context when needed.
5. Run analysis.
6. Review decoded output.
7. Review suspicious keyword matches.
8. Review risk score and reasons.
9. Review MITRE ATT&CK mappings.
10. Review detection rule mappings.
11. Review suggested Sigma or Sentinel detection templates.
12. Review the detection coverage summary.
13. Export results to JSON, CSV, Markdown, or HTML.
14. Attach output to triage notes or investigation documentation.

---

Detection Engineering Use Cases

This project can support:

• Alert triage
• Encoded PowerShell investigation
• Malware analysis support
• SOC analyst training
• Detection engineering testing
• SIEM rule validation
• Suspicious command-line review
• Investigation enrichment
• ATT&CK mapping practice
• Detection rule development
• Sigma rule drafting
• Microsoft Sentinel KQL drafting
• Detection coverage review
• Portfolio demonstration for detection engineering roles
• Case documentation and analyst reporting

---

Defensive Security Focus

This project is designed for defensive security use cases, including:

• Detection engineering
• Security operations
• Malware triage
• Incident response support
• Alert enrichment
• Analyst training
• Investigation documentation

It is not intended to execute decoded content.

---

Roadmap

Planned upgrades:

• Version 26: Add GUI case context fields
• Version 27: Add report branding or custom headers
• Version 28: Add external detection template files
• Version 29: Add YAML-based detection template library

---

Disclaimer

This tool is intended for defensive security, detection engineering, malware analysis support, and security training purposes only.

Decoded content should always be reviewed carefully in a controlled environment.

Generated detection templates are starter templates and should be validated, tested, and tuned before production deployment.

---

License

This project is licensed under the MIT License.