Skip to content

Commit fe2b591

Browse files
s4dhulabss4dhulabs
committed
Update install docs
1 parent 60d2c30 commit fe2b591

File tree

5 files changed

+373
-2
lines changed

5 files changed

+373
-2
lines changed

‎README.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,8 @@
2323

2424
## 📋 Documentation
2525

26-
- **[Installation Guide](docs/install.md)** - Setup instructions and deployment options
26+
- **[User Guide](docs/USER_GUIDE.md)** - Complete usage guide and command reference
27+
- **[Installation Guide](docs/INSTALL_GUIDE.md)** - Setup instructions and deployment options
2728
- **[CI/CD Integration](docs/pipelines/)** - Pipeline templates for GitHub Actions, GitLab CI/CD, CircleCI, Jenkins
2829

2930

‎core/vmnf_settings.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,5 +71,6 @@ settings:
7171
- viewscan
7272
- tictrac
7373
- fff
74+
- pyserial
7475
utils:
7576
random_headers: res/random_headers.yaml

‎docs/install.md renamed to ‎docs/INSTALL_GUIDE.md

File renamed without changes.

‎docs/USER_GUIDE.md

Lines changed: 369 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,369 @@
1+
# Vimana Framework User Guide
2+
3+
## Table of Contents
4+
- [Overview](#overview)
5+
- [Basic Command Structure](#basic-command-structure)
6+
- [Running Plugins](#running-plugins)
7+
- [Plugin Discovery and Documentation](#plugin-discovery-and-documentation)
8+
- [Advanced Usage Patterns](#advanced-usage-patterns)
9+
- [Case Management](#case-management)
10+
- [Examples and Best Practices](#examples-and-best-practices)
11+
12+
---
13+
14+
## Overview
15+
16+
The Vimana Framework provides a unified command-line interface for security testing and automation of Python web frameworks. The framework follows a plugin-based architecture where each security tool (called a "siddhi" or plugin) can be executed independently or as part of larger testing workflows.
17+
18+
### Core Philosophy
19+
20+
Vimana emphasizes:
21+
- **Simplicity**: Clear, intuitive command syntax
22+
- **Discoverability**: Built-in documentation and examples for every plugin
23+
- **Flexibility**: Support for standalone execution, cases, and workflows
24+
- **Extensibility**: Easy plugin development and integration
25+
26+
---
27+
28+
## Basic Command Structure
29+
30+
The primary command pattern for Vimana follows this structure:
31+
32+
```bash
33+
vimana run <plugin_name> <plugin_options>
34+
```
35+
36+
### Command Variations
37+
38+
```bash
39+
# Basic plugin execution
40+
vimana run <plugin_name> [options]
41+
42+
# Case execution
43+
vimana run --case <case_name>
44+
vimana run --case @<case_id>
45+
46+
# Workflow execution
47+
vimana run <workflow_name>
48+
49+
# Quick re-execution of last case
50+
vimana run !
51+
```
52+
53+
---
54+
55+
## Running Plugins
56+
57+
### Plugin Execution Basics
58+
59+
Every plugin in Vimana can be executed using the `vimana run` command. The framework includes 16 DAST (Dynamic Application Security Testing) tools, 1 SAST (Static Application Security Testing) tool, and 3 payload generators.
60+
61+
```bash
62+
# Example: Running DMT against a Django application
63+
vimana run dmt --target-url http://127.0.0.1:8000
64+
65+
# Example: Running JColt for FastAPI security testing
66+
vimana run jcolt --scan-api http://api.example.com
67+
68+
# Example: Running PySerial for serialization vulnerability testing
69+
vimana run pyserial --target-url http://127.0.0.1:8003
70+
```
71+
72+
### Common Plugin Options
73+
74+
While each plugin has unique capabilities, there are standard option patterns based on plugin type. Understanding these patterns helps you quickly get started with any plugin, but **always use `vimana guide -p <plugin_name>` for complete and accurate documentation**.
75+
76+
#### Option Categories by Plugin Type
77+
78+
| **DAST Plugins** (Dynamic Testing) | **SAST Plugins** (Static Analysis) | **Universal Options** |
79+
|-------------------------------------|-------------------------------------|----------------------|
80+
| `--target-url` - Single target URL | `--project-dir` - Project directory path | `--verbose` - Enable detailed output |
81+
| `--target-list` - Multiple targets (comma-separated) | `--framework` - Target framework (django, flask, fastapi) | `--debug` - Enable debug messages |
82+
| `--port` - Target port | `--framework-version` - Specific version to analyze | `--auto` - Auto-confirm prompts |
83+
| `--port-list` - Multiple ports | `--source-dirs` - Additional source directories | `--save-case <name>` - Save as reusable case |
84+
| `--file` - Load targets from file | `--exclude-dirs` - Directories to exclude | `--export-format` - Output format (json, xml, html) |
85+
| `--docker-scope` - Use Docker targets | `--include-tests` - Include test files in analysis | `--output` - Output file path |
86+
| `--scan-mode` - Testing mode (sample, full, etc.) | `--config-file` - Analysis configuration file | `--timeout` - Operation timeout |
87+
88+
#### Specialized Options by Domain
89+
90+
| **API Testing** (JColt, PySerial) | **Web App Testing** (DMT, D4M8) | **Framework Analysis** |
91+
|------------------------------------|----------------------------------|------------------------|
92+
| `--scan-api` - Discover and save API spec | `--sample` - Fast single-occurrence mode | `--fingerprint` - Identify framework/version |
93+
| `--apispec` - Use saved specification | `--exit-on-trigger` - Stop on first finding | `--enumerate-versions` - List supported versions |
94+
| `--list-specs` - Show saved specifications | `--extended-scope` - Comprehensive analysis | `--check-dependencies` - Analyze dependencies |
95+
| `--serialization-test` - Test serialization vulnerabilities | `--save-session` - Save interactive session | `--version-compare` - Compare against known versions |
96+
| `--pydantic-test` - Test Pydantic models | `--disable-cache` - Skip caching mechanisms | `--security-headers` - Analyze security headers |
97+
98+
#### Important Notes
99+
100+
- **Plugin-Specific Options**: Each plugin has unique capabilities beyond these common patterns
101+
- **Required vs Optional**: Some options are required, others are optional with sensible defaults
102+
- **Parameter Formats**: Check the guide for specific format requirements (e.g., comma-separated lists)
103+
- **Compatibility**: Not all options work together; the guide explains valid combinations
104+
105+
> **💡 Pro Tip**: The option patterns above are guidelines. For definitive information about any plugin's options, requirements, and usage examples, always run:
106+
> ```bash
107+
> vimana guide -p <plugin_name>
108+
> ```
109+
110+
---
111+
112+
## Plugin Discovery and Documentation
113+
114+
### The Guide System
115+
116+
Vimana includes a comprehensive built-in documentation system accessible via the `guide` command. This is your primary resource for understanding any plugin's capabilities and usage.
117+
118+
### Getting Complete Plugin Documentation
119+
120+
```bash
121+
# View full plugin guide (examples, arguments, lab setup)
122+
vimana guide -p <plugin_name>
123+
vimana guide --plugin <plugin_name>
124+
125+
# Example: Complete DMT documentation
126+
vimana guide -p dmt
127+
```
128+
129+
This displays:
130+
- **Plugin Overview**: Purpose and capabilities
131+
- **Usage Examples**: Real-world command examples with explanations
132+
- **Arguments Reference**: Complete list of available options
133+
- **Lab Setup**: Instructions for setting up test environments
134+
135+
### Getting Specific Documentation Sections
136+
137+
```bash
138+
# View only plugin arguments
139+
vimana guide -p <plugin_name> --args
140+
vimana guide -p <plugin_name> -a
141+
142+
# View only usage examples
143+
vimana guide -p <plugin_name> --examples
144+
vimana guide -p <plugin_name> -e
145+
146+
# View only lab setup instructions
147+
vimana guide -p <plugin_name> --labs
148+
vimana guide -p <plugin_name> -l
149+
```
150+
151+
### Example: DMT Plugin Documentation
152+
153+
```bash
154+
# Get complete DMT guide
155+
vimana guide -p dmt
156+
157+
# Get only DMT arguments
158+
vimana guide -p dmt --args
159+
160+
# Get only DMT examples
161+
vimana guide -p dmt --examples
162+
163+
# Get only DMT lab setup
164+
vimana guide -p dmt --labs
165+
```
166+
167+
---
168+
169+
## Advanced Usage Patterns
170+
171+
### Target Specification Methods
172+
173+
Vimana supports multiple ways to specify targets:
174+
175+
```bash
176+
# Single target
177+
vimana run dmt --target localhost --port 8000
178+
179+
# Multiple targets
180+
vimana run dmt --target-list 127.0.0.1,192.168.1.161 --port 9001
181+
182+
# Target file (format: target:port per line)
183+
vimana run dmt --file scope.txt
184+
185+
# Docker environment targets
186+
vimana run dmt --docker-scope
187+
188+
# Nmap XML import
189+
vimana run dmt --nmap-xml scan_results.xml
190+
```
191+
192+
### Execution Modes
193+
194+
Different plugins support various execution modes:
195+
196+
```bash
197+
# Sample mode (fast, single occurrence)
198+
vimana run dmt --target localhost --port 8000 --sample
199+
200+
# Exit on first trigger
201+
vimana run dmt --target localhost --port 8000 --exit-on-trigger
202+
203+
# Extended scope analysis
204+
vimana run dmt --target localhost --port 8000 --extended-scope
205+
206+
# Debug mode with verbose output
207+
vimana run dmt --target localhost --port 8000 --debug --verbose
208+
```
209+
210+
### Session Management
211+
212+
```bash
213+
# Save analysis results as interactive session
214+
vimana run dmt --target localhost --port 8000 --save-session
215+
216+
# Enable auto-confirmation for unattended execution
217+
vimana run dmt --target localhost --port 8000 --auto
218+
```
219+
220+
---
221+
222+
## Case Management
223+
224+
Cases allow you to save and reuse complex command configurations, making it easy to repeat security assessments or share testing procedures.
225+
226+
### Creating Cases
227+
228+
```bash
229+
# Create and execute a case
230+
vimana run dmt \
231+
--target-list 127.0.0.1,192.168.1.161,djapp1.vmnf.com \
232+
--port-list 8888,9001,8000,5001 \
233+
--verbose \
234+
--auto \
235+
--save-case djapps \
236+
--exec-case
237+
```
238+
239+
### Executing Saved Cases
240+
241+
```bash
242+
# Run case by name
243+
vimana run --case djapps
244+
245+
# Run case by ID
246+
vimana run --case @cf1
247+
248+
# Run the most recently created case
249+
vimana run !
250+
```
251+
252+
### Case Benefits
253+
254+
- **Reproducibility**: Exact same testing conditions
255+
- **Collaboration**: Share testing procedures with team members
256+
- **Automation**: Integrate into CI/CD pipelines
257+
- **Documentation**: Cases serve as executable documentation
258+
259+
---
260+
261+
## Examples and Best Practices
262+
263+
### FastAPI Security Testing with JColt
264+
265+
```bash
266+
# Scan API and save specification
267+
vimana run jcolt --scan-api http://api.example.com
268+
269+
# List available specifications
270+
vimana run jcolt --list-specs
271+
272+
# Run serialization tests against saved spec
273+
vimana run jcolt --serialization-test
274+
275+
# Run with custom payload builder
276+
vimana run jcolt --serialization-test --set-custom-payload
277+
```
278+
279+
### Python Serialization Testing with PySerial
280+
281+
```bash
282+
# Test using saved API specification
283+
vimana run pyserial --apispec aS0949
284+
285+
# Test with direct URL
286+
vimana run pyserial --target-url http://127.0.0.1:8003
287+
288+
# Test specific serialization categories
289+
vimana run pyserial --target-url http://127.0.0.1:8003 --test-categories depth_testing,type_confusion
290+
```
291+
292+
### Django Security Testing with DMT
293+
294+
```bash
295+
# Basic analytical mode (comprehensive)
296+
vimana run dmt --target djapp1.vmnf.com --port 8000 --debug
297+
298+
# Fast sample mode
299+
vimana run dmt --target-list 127.0.0.1,192.168.1.161 --port 9001 --sample
300+
301+
# Complex multi-target assessment
302+
vimana run dmt \
303+
--target-list 127.0.0.1,192.168.1.161,djapp1.vmnf.com \
304+
--port-list 8888,9001,8000,5001 \
305+
--verbose \
306+
--auto \
307+
--save-case production_scan
308+
```
309+
310+
### Plugin-Specific Options
311+
312+
Each plugin has unique capabilities. Always consult the plugin guide for specific options:
313+
314+
```bash
315+
# Check what a plugin can do
316+
vimana guide -p <plugin_name>
317+
318+
# Example: JColt-specific options
319+
vimana run jcolt --pydantic-test --test-types validation_bypass,injection
320+
vimana run jcolt --apispec aS0949 --list-pydantic-models
321+
vimana run jcolt --fingerprint --target-url http://api.example.com
322+
```
323+
324+
### Best Practices
325+
326+
1. **Start with the Guide**: Always run `vimana guide -p <plugin_name>` before using a new plugin
327+
2. **Use Cases for Repeatability**: Save complex configurations as cases
328+
3. **Enable Debug for Learning**: Use `--debug` when learning plugin behavior
329+
4. **Leverage Auto Mode**: Use `--auto` for unattended execution
330+
5. **Organize Your Tests**: Use descriptive case names and maintain documentation
331+
332+
### Lab Environment Setup
333+
334+
For hands-on learning, set up test environments using vulnerable applications:
335+
336+
```bash
337+
# Example: Django.nV setup for DMT testing
338+
git clone https://github.com/nVisium/django.nV.git
339+
cd django.nV
340+
# Follow plugin-specific lab setup instructions from guide
341+
```
342+
343+
---
344+
345+
## Getting Help
346+
347+
### Built-in Documentation
348+
349+
```bash
350+
# Main framework help
351+
vimana --help
352+
353+
# Plugin-specific documentation
354+
vimana guide -p <plugin_name>
355+
356+
# Plugin catalog
357+
vimana list --plugins
358+
```
359+
360+
### Community Resources
361+
362+
- **Installation Guide**: [docs/install.md](install.md)
363+
- **CI/CD Integration**: [docs/pipelines/](pipelines/)
364+
- **Plugin Development**: Coming soon
365+
- **API Reference**: Coming soon
366+
367+
---
368+
369+
*Remember: The `guide` command is your best friend. When in doubt, run `vimana guide -p <plugin_name>` to understand any plugin's capabilities, arguments, and usage patterns.*

‎siddhis/dmt/dmt.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ guide:
8989
ø-----------+----------------------------------------------------------ø
9090
│ target └┐ │
9191
+------------+---------------------------------------------------------+
92-
--target Run DMT against a single target
92+
--target-url Run DMT against a single target URL
9393
--target-list Run DMT against a target list (comma separated)
9494
--file Run DMT loading scope from a file
9595
+-----------+----------------------------------------------------------+

0 commit comments

Comments
 (0)