kitos/Angerona
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Artifacts created

Browse Source
This commit is contained in:
marcos.luna
2025-10-29 13:42:28 +01:00
parent aeb74259c7
commit df8e824f5f
7 changed files with 424 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+273 -4
View File
@@ -22,6 +22,8 @@
- [SOCKS Proxy Support](#socks-proxy-support)
- [Communication Protocol](#communication-protocol)
- [Configuration](#configuration)
- [Process Browser Integration](#process-browser-integration)
- [Artifacts Support](#artifacts-support)
- [Development](#development)
- [Troubleshooting](#troubleshooting)
- [Credits](#credits)
@@ -42,6 +44,8 @@ This project was inspired by the article [How to build your own Mythic agent in
- **Lightweight & Portable**: Minimal dependencies, compiled with MinGW for Windows targets
- **Full Mythic Integration**: Native support for Mythic's translator pattern and RPC system
- **Channel Encryption**: Optional AES-256-CBC encryption with HMAC-SHA256 for secure communication
- **Process Browser Support**: Integrated with Mythic's Process Browser for unified process management across multiple callbacks
- **SOCKS Proxy**: Route traffic through the implant with built-in SOCKS5 support
- **Dynamic Sleep**: Automatically adjusts beacon interval based on proxy activity
- **Custom Binary Protocol**: Efficient binary communication with base64 encoding
@@ -188,7 +192,9 @@ For more information, see the [Mythic documentation on customizing public agents
| Command | Description | Example |
|---------|-------------|---------|
| `ps` | List running processes | `ps` |
| `ps` | List running processes with Process Browser support | `ps` |
**Note**: The `ps` command integrates with Mythic's Process Browser, allowing unified process management across multiple callbacks. Process lists are automatically synchronized and viewable from the Process Browser UI.
### Network Operations
@@ -361,6 +367,16 @@ Example command IDs:
All binary data is base64-encoded for transport over HTTP/HTTPS.
### Channel Encryption (Optional)
When encryption is enabled via the `AESPSK` build parameter:
- **Encryption Format**: `[IV:16 bytes][AES-256-CBC Ciphertext][HMAC-SHA256:32 bytes]`
- **Agent Side**: Encrypts all outgoing messages before base64 encoding
- **Translator Side**: Decrypts all incoming messages after base64 decoding
- **Key Management**: 256-bit AES key embedded at build time, unique per payload
This provides end-to-end encryption independent of the transport layer (HTTP/HTTPS).
---
## ⚙️ Configuration
@@ -374,6 +390,10 @@ When building from Mythic UI:
- **User Agent**: HTTP User-Agent string
- **Sleep**: Initial beacon interval in seconds (default: 10)
- **Jitter**: Random delay percentage (0-100)
- **Encryption**: Channel encryption settings (optional)
- **AESPSK**: Enable AES-256-CBC encryption with HMAC-SHA256
- When enabled, all agent ↔ Mythic communication is encrypted end-to-end
- The encryption key is automatically generated by Mythic and embedded in the payload
### Compile-Time Options
@@ -385,6 +405,44 @@ Edit `Config.h` before building:
#define SOCKS_TIMEOUT_SEC 60 // Socket read timeout
```
### Channel Encryption
Cazalla supports optional AES-256-CBC encryption with HMAC-SHA256 for secure agent-to-Mythic communication. This provides an additional layer of security beyond HTTPS.
#### How It Works
1. **Mythic generates** a random 256-bit AES key during payload creation
2. **Key is embedded** in the agent binary at build time
3. **All messages** are encrypted using AES-256-CBC mode with a random IV per message
4. **HMAC-SHA256** is calculated over the IV + ciphertext for integrity verification
5. **Format**: `[IV:16 bytes][Ciphertext:N bytes][HMAC:32 bytes]`
#### Enabling Encryption
Encryption is enabled automatically when building with the `AESPSK` parameter in Mythic's UI:
1. Navigate to **Payloads** → **Create Payload**
2. Select **Cazalla** as the payload type
3. In the build parameters, configure **AESPSK**:
- Set `crypto_type` to `aes256_hmac`
- Mythic will automatically generate an `enc_key`
4. Click **Build**
The encryption key is unique per payload and is shared between the agent and translator.
#### Encryption Status
You can verify encryption is enabled by checking the build output:
- Look for: `✓ Encryption ENABLED: crypto_type=aes256_hmac, enc_key present`
- The translator logs will show encryption/decryption operations
#### Security Considerations
- **Key Management**: Each payload has a unique encryption key managed by Mythic
- **IV Randomization**: A new random IV is generated for each encrypted message
- **HMAC Verification**: All encrypted messages include HMAC for integrity validation
- **Defense in Depth**: Encryption works alongside HTTPS for layered security
### Debug Mode
Enable verbose logging by defining `DEBUG_SOCKS` during compilation:
@@ -401,6 +459,174 @@ This enables:
---
## 📊 Process Browser Integration
Cazalla's `ps` command fully integrates with Mythic's Process Browser feature, providing unified process management across multiple callbacks on the same host.
### Features
- **Unified Process Lists**: All process listings from different callbacks on the same host are aggregated
- **Process Hierarchy**: View process parent-child relationships when parent process IDs are available
- **Rich Process Data**: Includes process name, PID, PPID, architecture, user account, and session ID
- **Automatic Synchronization**: Process lists are automatically synchronized with Mythic's Process Browser UI
### Process Browser UI
Access the Process Browser in Mythic:
1. Navigate to a callback in the Mythic UI
2. Click the **PROCESSES** tab (next to the **CALLBACK** tab)
3. View all processes from all callbacks on that host
4. Use the UI buttons for additional actions (inject, kill, etc.) if implemented
### Implementation Details
The `ps` command implements the `process_browser:list` supported UI feature:
- Process data is automatically converted to Mythic's Process Browser JSON format
- The translator detects process list responses and formats them accordingly
- Process information includes:
- `process_id`: Process identifier (required)
- `name`: Process name (required)
- `parent_process_id`: Parent process ID (optional)
- `architecture`: Process architecture (x64/x86)
- `user`: User account running the process
- `session_id`: Windows session ID
For more information, see the [Mythic Process Browser documentation](https://docs.mythic-c2.net/customizing/hooking-features/process_list).
---
## 🎨 Artifacts Support
Cazalla automatically reports artifacts created during command execution, allowing Mythic to track artifacts like process creation, file writes, and other system modifications.
### Features
- **Automatic Artifact Detection**: Shell commands automatically report Process Create artifacts
- **Process Create Tracking**: Every `shell` command execution creates an artifact showing the command line
- **Artifact Management**: Artifacts appear in Mythic's Artifacts page (click the fingerprint icon)
- **Extensible**: Easy to add artifact reporting for other commands (File Write, Network Connection, etc.)
### How It Works
1. **Agent Execution**: When a command like `shell whoami` is executed, the agent:
- Executes the command via `_popen()`
- Captures the output
- Includes the command string in the response payload
2. **Translator Detection**: The translator detects the command in the response:
- Looks for the artifact marker (`0xFF`) in the response
- Extracts the command string
- Creates a `Process Create` artifact entry
3. **Mythic Integration**: The artifact is automatically:
- Added to the response JSON
- Tracked in Mythic's Artifacts page
- Associated with the task and callback
### Example Artifact Response
When you execute `shell whoami`, the response includes:
```json
{
"task_id": "...",
"user_output": "CETP-WIN11-01\\localuser",
"artifacts": [
{
"base_artifact": "Process Create",
"artifact": "whoami",
"needs_cleanup": false,
"resolved": false
}
]
}
```
### Viewing Artifacts
1. Navigate to your callback in the Mythic UI
2. Click the **Artifacts** icon (fingerprint) in the top navigation
3. View all artifacts created by all commands across all callbacks
4. Filter by artifact type, needs cleanup, resolved status, etc.
### Supported Artifact Types
Currently supported:
- **Process Create**: Automatically reported for all `shell` commands
- **File Write**: Automatically reported for:
- `cp` (copy) - reports destination file path
- `mkdir` (create directory) - reports created directory path
- `rm` (delete) - reports deleted file/directory path
**Note**: The following commands don't require artifacts as they are read-only or don't modify system state:
- `ls`, `cd`, `pwd` - read-only file system operations
- `ps` - already integrated with Process Browser
- `sleep`, `exit` - don't modify system state
Future support can be added for:
- **File Read**: When files are downloaded/read (e.g., `download` command)
- **File Write**: For file upload operations (e.g., `upload` command)
- **Network Connection**: When network operations occur (e.g., for `socks` proxy connections)
- **Registry Modification**: When registry keys are modified (e.g., `reg_set`, `reg_delete`)
- **Process Inject**: When processes are injected into (e.g., `inject` command)
### Implementation Details
The artifact system uses:
- **Agent Side Helper** (`paquete.c`): `addArtifact()` function to easily add artifacts to any command response
- **Agent Side** (command handlers): Call `addArtifact(paquete, "Artifact Type", "artifact value")` after adding response output
- **Translator Side** (`commands_from_implant.py`): Automatically detects, parses, and creates artifact JSON for all artifact types
- **Helper Function**: `create_artifact()` in the translator provides a clean API for creating artifacts
### Extending Artifacts for Other Commands
To add artifact support to other commands, use the `addArtifact()` helper function:
1. **Include the header** in your C file:
```c
#include "paquete.h"
```
2. **Add artifact in your command handler**:
```c
// After adding the response output
addBytes(respuestaTarea, (PBYTE)salida->buffer, salida->length, TRUE);
// Add artifact using the helper function
addArtifact(respuestaTarea, "Artifact Type", "artifact value");
```
3. **The translator automatically detects and creates the artifact** - no changes needed!
Example implementations:
- `shell`: Process Create artifact with command
- `cp`: File Write artifact with destination path
- `mkdir`: File Write artifact with directory path
- `rm`: File Write artifact with deleted path
### Best Practices for New Commands
**When developing new commands, always consider artifact reporting:**
✅ **Commands that SHOULD report artifacts:**
- Any command that creates, modifies, or deletes files (`cp`, `mkdir`, `rm`, `upload`, `download`)
- Any command that executes processes (`shell`, `execute`, `inject`)
- Any command that modifies registry (`reg_set`, `reg_delete`)
- Any command that creates network connections (`socks`, custom network commands)
- Any command that modifies system configuration
❌ **Commands that DON'T need artifacts:**
- Read-only operations (`ls`, `cd`, `pwd`, `cat`, `read`)
- Information gathering commands (`ps`, `whoami`, `hostname`) - unless they create processes
- Commands that only change local state (`sleep`, `exit`)
**Rule of thumb**: If the command modifies system state or creates forensic evidence, it should report an artifact.
For more information, see the [Mythic Artifacts documentation](https://docs.mythic-c2.net/customizing/hooking-features/artifacts).
---
## 🔧 Development
### Project Structure
@@ -414,17 +640,20 @@ Cazalla/
│ ├── paquete.c/h # Packet creation
│ ├── transporte.c/h # HTTP transport (WinHTTP)
│ ├── socks_manager.c/h # SOCKS proxy logic
│ ├── procesos.c/h # Process listing (with Process Browser support)
│ ├── crypto.c/h # AES-256-CBC encryption with HMAC-SHA256
│ ├── checkin.c/h # Initial check-in
│ └── Makefile # Build configuration
├── agent_functions/ # Python command definitions
│ ├── ls.py, cd.py, pwd.py # File system commands
│ ├── shell.py, sleep.py # Execution control
│ ├── ps.py # Process listing (Process Browser enabled)
│ ├── socks.py # SOCKS proxy command
│ └── builder.py # Payload builder
│ └── builder.py # Payload builder (with encryption support)
├── translator/ # Mythic ↔ Agent translation
│ ├── translator.py # Main translator
│ ├── translator.py # Main translator (with encryption support)
│ ├── commands_from_c2.py # Mythic JSON → Binary
│ └── commands_from_implant.py # Binary → Mythic JSON
│ └── commands_from_implant.py # Binary → Mythic JSON (Process Browser parser)
└── browser_scripts/ # Mythic UI enhancements
├── ls.js # Directory listing formatter
└── ps.js # Process list formatter
@@ -432,6 +661,8 @@ Cazalla/
### Adding New Commands
**Important**: When developing new commands, always consider whether the command should report artifacts. Commands that modify system state (create processes, write files, modify registry, create network connections, etc.) should include artifact reporting using the `addArtifact()` helper function. See [Artifacts Support](#artifacts-support) for details.
1. **Define command in Python** (`agent_functions/my_command.py`):
```python
@@ -476,6 +707,8 @@ elif task_command == "my_command":
3. **Implement handler in C** (`comandos.c`):
**Remember to add artifacts if the command modifies system state!** After adding the response output, use `addArtifact()` to report the action:
```c
BOOL myCommandHandler(PAnalizador argumentos) {
SIZE_T tamanoUuid = 36;
@@ -491,6 +724,13 @@ BOOL myCommandHandler(PAnalizador argumentos) {
addString(respuesta, taskUuid, FALSE);
PackageAddFormatPrintf(respuesta, "Command executed: %s\n", arg1);
// IMPORTANT: Add artifact if this command modifies system state
// Examples:
// - If creating/modifying files: addArtifact(respuesta, "File Write", file_path);
// - If creating processes: addArtifact(respuesta, "Process Create", command);
// - If modifying registry: addArtifact(respuesta, "Registry Write", reg_key);
// - If creating network connections: addArtifact(respuesta, "Network Connection", connection_info);
Analizador* resp = mandarPaquete(respuesta);
liberarPaquete(respuesta);
if (resp) liberarAnalizador(resp);
@@ -559,11 +799,40 @@ apt-get update && apt-get install -y mingw-w64
- Mark task as completed in `create_go_tasking` or `process_response`
- For `exit`, mark completed immediately (agent terminates)
### Process Browser Not Showing Processes
**Processes not appearing in Process Browser:**
- Verify `ps` command executed successfully (check callback output)
- Check translator logs: `sudo docker logs cazalla_translator | grep PROCESS_BROWSER`
- Ensure `supported_ui_features = ["process_browser:list"]` is set in `ps.py`
- Verify processes are being parsed correctly (translator should show "Parseados X procesos")
- Rebuild translator if changes were made: `sudo ./mythic-cli build cazalla`
**Processes showing as "UNKNOWN - MISSING DATA":**
- This usually indicates processes that couldn't be accessed (protected/system processes)
- Check if the issue persists after rebuilding the agent
- Some processes may legitimately lack certain information (e.g., system processes)
### Encryption Issues
**Encryption not working:**
- Verify `AESPSK` parameter is configured in build parameters
- Check build output for: `✓ Encryption ENABLED`
- Review translator logs for encryption/decryption errors: `sudo docker logs cazalla_translator | grep CRYPTO`
- Ensure encryption key is present in both agent and translator (auto-configured by Mythic)
**"HMAC verification failed" errors:**
- Usually indicates key mismatch between agent and translator
- Rebuild the payload to regenerate the encryption key
- Check that both agent and translator are using the same payload UUID
---
## 📚 References
- [Mythic Documentation](https://docs.mythic-c2.net/)
- [Mythic Process Browser](https://docs.mythic-c2.net/customizing/hooking-features/process_list)
- [Mythic Customizing Public Agents](https://docs.mythic-c2.net/customizing/customizing-public-agent)
- [Building a Mythic Agent in C](https://red-team-sncf.github.io/how-to-create-your-own-mythic-agent-in-c.html)
- [SOCKS5 Protocol (RFC 1928)](https://www.rfc-editor.org/rfc/rfc1928)
- [Mythic Translator Pattern](https://docs.mythic-c2.net/customizing/payload-type-development/translation-containers)