Vimana Framework v0.1 - Installation Guide

📋 Installation Quick Navigator

Choose your preferred installation method and jump directly to the instructions:

🚀 Quick & Easy	🔧 Development	🏗️ CI/CD Integration
One-Line Install Fastest way to get started `curl \| bash`	Manual Setup Full control & customization `git clone + setup`	⚡ GitHub Actions Automated security scanning `.github/workflows/`
UV Package Manager Modern Python tooling `setup-uv script`	Docker Container Isolated environment `docker run`	⭕ CircleCI Enterprise CI/CD `.circleci/config.yml`
Pip Installation Traditional Python setup `setup-pip script`	Virtual Environment Python isolation `venv + pip`	🦊 GitLab & 🔧 Jenkins Self-hosted pipelines `.gitlab-ci.yml`

🎯 Recommended Paths:

🆕 New Users: Start with One-Line Install → Get running in 30 seconds
👨‍💻 Developers: Use Manual Setup → Full development environment
🏢 Enterprise: Implement CI/CD Integration → Automated security testing
🐳 DevSecOps: Deploy with Docker → Containerized security scanning

🚀 Quick Start

Option 1: UV Installation (Recommended - Fastest)

# Super short one-liner (installs to ~/vimana-framework)
curl -s https://raw.githubusercontent.com/s4dhulabs/vimana-framework/develop/scripts/install | bash

Or traditional way (UV):

# Clone the repository and set Vimana using uv
git clone -b develop https://github.com/s4dhulabs/vimana-framework.git && cd vimana-framework && source scripts/setup-uv

Stage 1: Dependency Installation The installer downloads and configures UV, then creates a virtual environment and installs all Python dependencies. This stage handles the complete dependency resolution and builds the Vimana framework package from source.

Stage 2: Plugin System Initialization After successful dependency installation, Vimana loads and configures its plugin ecosystem. This includes scanning for available plugins, initializing the framework core, and preparing the plugin catalog for first use.

Stage 3: Installation Complete The final stage shows the Vimana Framework ready for use, displaying the plugin catalog with available security testing tools. The framework is now fully operational with all plugins properly registered and accessible.

To activate the environment and use Vimana, just run source vfe:

Why UV?

10-100x faster than pip
Automatic dependency resolution
Built-in virtual environment management
Lock file support for reproducible builds
Uses uv sync for optimal project setup
Clean setup experience - warnings are suppressed during installation

Important: Always use source scripts/setup-uv (not ./scripts/setup-uv) to ensure the virtual environment stays active in your current shell session.

🔄 Using Vimana After Installation

If you used the one-liner installer, Vimana is installed to ~/vimana-framework. To use it in future sessions:

# Super quick activation:
source vfe          # Activate environment from anywhere
vimana              # Run Vimana (after activation)

What is vfe?

VFE: Vimana Framework Environment
source vfe: Activates environment from anywhere, stays active
Works from any directory
Automatically checks if Vimana is properly installed
Use deactivate to exit the environment

Option 2: Pip Installation (Traditional)

# Clone to home directory and set Vimana using pip
cd ~ && git clone -b develop https://github.com/s4dhulabs/vimana-framework.git && cd vimana-framework && source scripts/setup-pip

Traditional Python setup:

Uses standard python -m venv and pip
Compatible with all Python environments
Familiar workflow for Python developers
Same clean setup experience as UV

🔧 Manual Installation

For developers who prefer full control over the installation process or want to customize the setup:

# Clone the repository
git clone -b develop https://github.com/s4dhulabs/vimana-framework.git
cd vimana-framework

# Create a Python virtual environment
python3 -m venv .venv

# Activate the virtual environment
source .venv/bin/activate  # On Linux/macOS
# .venv\Scripts\activate   # On Windows

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

# Run Vimana
python vimana.py --help

Manual setup benefits:

✅ Full Control: Customize every step of the installation
✅ Development Ready: Perfect for contributing to Vimana
✅ Environment Isolation: Uses standard Python virtual environments
✅ No Scripts: Direct control without automation scripts
✅ Debugging Friendly: Easy to troubleshoot installation issues

Usage after manual installation:

# Activate environment (required each time)
cd ~/vimana-framework && source .venv/bin/activate

# Run Vimana commands
python vimana.py list --plugins
python vimana.py run framewalk --target-url http://example.com

# Deactivate when done
deactivate

🐳 Docker Installation

Option 1: Docker Compose (Recommended for development)

# Clone the repository
git clone -b develop https://github.com/s4dhulabs/vimana-framework.git && cd vimana-framework

# Start with docker compose
docker compose up -d

# Or run interactively
docker compose run --rm vimana

# Stop the services
docker compose down

Benefits of Docker Compose:

Persistent volume mounting for data
Easy environment management
Port exposure for web interfaces
Automatic restart policies

Option 2: Direct Docker Build

# Clone the repository
git clone -b develop https://github.com/s4dhulabs/vimana-framework.git && cd vimana-framework

# Build and run using the build script
sudo sh scripts/build

# Or build manually
docker build -t vimana_framework:v0.1 .

# Run the container
docker run -it vimana_framework:v0.1

⚡ GitHub Actions Integration

Vimana Framework supports running security scans directly in GitHub Actions CI/CD pipelines using various plugins.

Quick Setup

Copy our ready-to-use template:

# Create workflow directory
mkdir -p .github/workflows

# Copy template
curl -O https://raw.githubusercontent.com/s4dhulabs/vimana-framework/develop/docs/pipelines/github-actions-basic.yml
mv github-actions-basic.yml .github/workflows/vimana-scan.yml

# Commit and push
git add .github/workflows/vimana-scan.yml
git commit -m "Add Vimana security scanning workflow"
git push

Automated Scanning in Your Repository

Or create your own workflow file:

name: Vimana Workflow

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  vimana_scan:
    runs-on: ubuntu-22.04   
    steps:
      - uses: actions/checkout@v4

      - name: Setup python
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'

      - name: Install Vimana
        run: |
          curl -s https://raw.githubusercontent.com/s4dhulabs/vimana-framework/develop/scripts/install | bash
          export PATH="$HOME/.local/bin:$PATH"
          source $HOME/.local/bin/env || true

When the workflow runs successfully, you'll see output similar to the images below, showing:

The successful installation and setup of Vimana Framework
The environment configuration and path setup
A list of available security scanning plugins ready to be used in your CI/CD pipeline

These screenshots demonstrate that Vimana is properly integrated into your GitHub Actions workflow and ready to perform security scans:

Running plugins (framewalk workflow)

For complete Django security analysis, use our comprehensive template:

# Copy Django-specific template
curl -O https://raw.githubusercontent.com/s4dhulabs/vimana-framework/develop/docs/pipelines/github-actions-django.yml
mv github-actions-django.yml .github/workflows/vimana-django-scan.yml

Below is an example workflow that demonstrates how to use Vimana's framewalk plugin to scan a Django application for security vulnerabilities. The workflow will:

Install and configure Vimana Framework
Start a Django test application
Run the framewalk plugin against the application
Generate and store the scan report artifact

Here's the complete workflow:

name: Vimana Framewalk Scan

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build_app:
    runs-on: ubuntu-22.04   
    steps:
      - uses: actions/checkout@v4

      - name: Setup python
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'

      - name: Install venv and distutils for Python
        run: |
          sudo apt-get update
          sudo apt-get install -y python3.10-venv python3.10-distutils

      - name: Set up venv and install dependencies
        run: |
          python3.10 -m venv env
          source env/bin/activate
          pip install --upgrade pip
          pip install -r requirements.txt
          python manage.py check

  run_app_and_scan:
    runs-on: ubuntu-22.04   
    steps:
      - uses: actions/checkout@v4

      - name: Setup python
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'

      - name: Install venv and distutils for Python
        run: |
          sudo apt-get update
          sudo apt-get install -y python3.10-venv python3.10-distutils

      - name: Set up venv and run the App
        run: |
          python3.10 -m venv env
          source env/bin/activate
          pip install --upgrade pip
          pip install -r requirements.txt
          nohup python manage.py runserver 0.0.0.0:8000 & sleep 10

      - name: Install Vimana
        run: |
          curl -s https://raw.githubusercontent.com/s4dhulabs/vimana-framework/develop/scripts/install | bash
          export PATH="$HOME/.local/bin:$PATH"
          source $HOME/.local/bin/env || true

      - name: Run Vimana Framewalk
        env:
          PYTHONWARNINGS: ignore
        run: |
          cd ~/vimana-framework && source .venv/bin/activate
          export REPORT=framewalk_report_$(date +%Y%m%d_%H%M%S).json
          vimana run framewalk --target-url http://127.0.0.1:8000/ --output $REPORT
          echo "REPORT=$REPORT" >> $GITHUB_ENV
          echo "* Final plugin report: $REPORT"

      - name: Upload Framewalk Report
        uses: actions/upload-artifact@v4
        with:
          name: framewalk-report
          path: ~/vimana-framework/${{ env.REPORT }}

⭕ CircleCI Integration

Vimana Framework integrates seamlessly with CircleCI for automated security testing in your CI/CD pipeline. This example demonstrates how to set up a Django application with Vimana Framewalk scanning.

Quick Setup

Copy our ready-to-use template:

# Create config directory
mkdir -p .circleci

# Copy template
curl -O https://raw.githubusercontent.com/s4dhulabs/vimana-framework/develop/docs/pipelines/circleci-config.yml
mv circleci-config.yml .circleci/config.yml

# Commit and push
git add .circleci/config.yml
git commit -m "Add Vimana security scanning pipeline"
git push

Pipeline Overview

The CircleCI workflow consists of five sequential jobs that build, test, and security-scan a Django application:

Build - Sets up Python environment and validates Django application
Test - Runs Django unit tests to ensure application functionality
Run App and Scan - Deploys Django app and performs Vimana Framewalk security analysis
Integration - Integration testing phase
Prod - Production deployment (requires manual approval)

CircleCI Configuration

Create a .circleci/config.yml file in your Django project:

version: 2.1

jobs:
  build:
    docker:
      - image: python:3.10
    steps:
      - checkout
      - run:
          name: Install system dependencies
          command: |
            apt-get update
            apt-get install -y python3-venv curl
      - run:
          name: Set up virtual environment and install dependencies
          command: |
            python -m venv env
            source env/bin/activate
            pip install --upgrade pip
            pip install -r requirements.txt
            python manage.py check

  test:
    docker:
      - image: python:3.10
    steps:
      - checkout
      - run:
          name: Install dependencies and run tests
          command: |
            python -m venv env
            source env/bin/activate
            pip install --upgrade pip
            pip install -r requirements.txt
            python manage.py test taskManager

  run_app_and_scan:
    docker:
      - image: python:3.10
    steps:
      - checkout
      - run:
          name: Install system dependencies
          command: |
            apt-get update
            apt-get install -y python3-venv curl sudo
      - run:
          name: Set up virtual environment and run Django app
          command: |
            python -m venv env
            source env/bin/activate
            pip install --upgrade pip
            pip install -r requirements.txt
            nohup python manage.py runserver 0.0.0.0:8000 & sleep 10
          background: true
      - run:
          name: Install Vimana Framework
          command: |
            curl -s https://raw.githubusercontent.com/s4dhulabs/vimana-framework/develop/scripts/install | bash
      - run:
          name: Create workspace directory
          command: mkdir -p /tmp/workspace
      - run:
          name: Run Vimana Framewalk Scan
          environment:
            PYTHONWARNINGS: ignore
          command: |
            cd ~/vimana-framework && source .venv/bin/activate
            export REPORT=framewalk_report_$(date +%Y%m%d_%H%M%S).json
            vimana run framewalk --target-url http://127.0.0.1:8000/ --output $REPORT
            echo "* Final plugin report: $REPORT"
            # Copy report to workspace for artifact storage
            cp $REPORT /tmp/workspace/
      - persist_to_workspace:
          root: /tmp/workspace
          paths:
            - framewalk_report_*.json
      - store_artifacts:
          path: /tmp/workspace
          destination: vimana-reports

  integration:
    docker:
      - image: python:3.10
    steps:
      - checkout
      - run:
          command: |
            echo "~ Integration step"
            exit 1
          when: on_fail

  prod:
    docker:
      - image: python:3.10
    steps:
      - checkout
      - run: echo "~ Deploy step"

workflows:
  version: 2
  django_with_vimana:
    jobs:
      - build
      - test:
          requires:
            - build
      - run_app_and_scan:
          requires:
            - test
      - integration:
          requires:
            - test
            - run_app_and_scan
      - prod:
          type: approval
          requires:
            - integration

Pipeline Execution Flow

1. Pipeline Overview

The CircleCI dashboard shows the complete workflow execution with visual status indicators for each job. The pipeline runs sequentially with dependency management ensuring proper build order.

2. Vimana Installation Process

The installation step demonstrates:

Automated Setup: Vimana Framework downloads and configures automatically
Environment Creation: Virtual environment setup at /root/vimana-framework/.venv
Dependency Resolution: All required packages installed and validated
Symlink Creation: Global vimana command made available system-wide

3. Security Scanning Execution

The Framewalk scan process shows:

Target Detection: Django application running on localhost:8000
Framework Analysis: Comprehensive Django security assessment
Report Generation: Timestamped JSON report with findings
Passive Scanning: Non-intrusive analysis maintaining application stability

4. Artifact Management

The pipeline automatically:

Generates Reports: Creates timestamped security analysis files
Stores Artifacts: Preserves scan results for download and analysis
Workspace Persistence: Maintains reports across pipeline stages
Download Access: Provides easy access to security findings

Key Benefits

🔄 Automated Security: Every code change triggers security analysis
📊 Comprehensive Reports: Detailed Django framework vulnerability assessment
🎯 Passive Scanning: Non-disruptive analysis during CI/CD process
📦 Artifact Storage: Persistent security reports for compliance and analysis
🚀 Parallel Execution: Security scanning runs alongside other pipeline jobs
🛡️ Framework-Specific: Targeted Django security analysis with Framewalk plugin

Usage Examples

# Trigger pipeline on push
git push origin main

# Download security reports
# Available in CircleCI Artifacts tab: vimana-reports/framewalk_report_*.json

# View scan results
curl -H "Circle-Token: $CIRCLECI_TOKEN" \
  "https://circleci.com/api/v1.1/project/github/$USER/$REPO/latest/artifacts"

🦊 GitLab & 🔧 Jenkins Integration

Vimana Framework can be integrated into GitLab CI/CD and Jenkins pipelines for automated security testing.

🦊 GitLab CI/CD Pipeline

Quick Setup

Copy our ready-to-use template:

# Copy basic template
curl -O https://raw.githubusercontent.com/s4dhulabs/vimana-framework/develop/docs/pipelines/gitlab-ci-basic.yml
mv gitlab-ci-basic.yml .gitlab-ci.yml

# Or copy Django-specific template
curl -O https://raw.githubusercontent.com/s4dhulabs/vimana-framework/develop/docs/pipelines/gitlab-ci-django.yml
mv gitlab-ci-django.yml .gitlab-ci.yml

# Commit and push
git add .gitlab-ci.yml
git commit -m "Add Vimana security scanning pipeline"
git push

Manual Configuration

Or create your own .gitlab-ci.yml file:

Basic Setup - Framework Installation Only

stages:
  - security-test

vimana-framework-setup:
  stage: security-test
  image: python:3.10
  variables:
    PYTHONWARNINGS: ignore
  before_script:
    - apt-get update && apt-get install -y curl sudo git
    - curl -s https://raw.githubusercontent.com/s4dhulabs/vimana-framework/develop/scripts/install | bash
  script:
    - source vfe 
    - vimana list --plugins

Pipeline execution showing successful Vimana installation:

Framework activation and plugin catalog display:

Complete Pipeline - Django Application Security Analysis (Passive Framework Fingerprint)

image: docker:20.10

services:
  - docker:dind

stages:
  - build
  - test
  - security-scan
  - integration
  - prod

variables:
  PYTHONWARNINGS: ignore

build:
  stage: build
  image: python:3.10
  before_script:
    - pip3 install --upgrade virtualenv
  script:
    - virtualenv env
    - source env/bin/activate
    - pip install -r requirements.txt
    - python manage.py check
  artifacts:
    paths:
      - env/
    expire_in: 1 hour

test:
  stage: test
  image: python:3.10
  dependencies:
    - build
  script:
    - source env/bin/activate
    - python manage.py test taskManager

vimana_framewalk_scan:
  stage: security-scan
  image: python:3.10
  variables:
    PYTHONWARNINGS: ignore
  dependencies:
    - build
  before_script:
    - apt-get update && apt-get install -y curl sudo git
    - echo "Installing Vimana Security Framework"
    - curl -s https://raw.githubusercontent.com/s4dhulabs/vimana-framework/develop/scripts/install | bash
  script:
    - echo "Starting Django development server"
    - source env/bin/activate
    - nohup python manage.py runserver 0.0.0.0:8000 > django.log 2>&1 &
    - sleep 15
    - echo "Verifying Django server accessibility"
    - curl -L http://127.0.0.1:8000/taskManager/ || echo "Django server not accessible"
    - echo "Executing Vimana Framewalk security scan"
    - cd ~/vimana-framework && source .venv/bin/activate
    - export REPORT_NAME="framewalk_security_report_$(date +%Y%m%d_%H%M%S).json"
    - export REPORT_PATH="/tmp/$REPORT_NAME"
    - vimana run framewalk --target-url http://127.0.0.1:8000/ --output $REPORT_PATH
    - echo "Security analysis completed"
    - echo "Report size: $(du -h $REPORT_PATH | cut -f1)"
    - head -20 $REPORT_PATH || echo "Report file not found or empty"
  artifacts:
    name: "vimana-security-report-$CI_COMMIT_SHORT_SHA"
    paths:
      - /tmp/framewalk_security_report_*.json
    when: always
    expire_in: one week
  allow_failure: true

integration:
  stage: integration
  image: python:3.10
  script:
    - echo "Running integration tests"
    - echo "This is an integration step"
    - exit 1
  allow_failure: true

prod:
  stage: prod
  image: python:3.10
  script:
    - echo "Deploying to production"
    - echo "This is a deploy step"
  when: manual
  only:
    - main
    - master

Complete pipeline execution with all stages:

Framewalk security scan execution and framework discovery:

Security analysis report generation and artifact collection:

Key Benefits

🔄 Automated Security: Security scanning integrated into GitLab CI/CD pipeline
📊 Detailed Reports: Comprehensive vulnerability assessment reports
🎯 Flexible Integration: Works with both basic and Django-specific pipelines
📦 Artifact Storage: Security reports preserved as pipeline artifacts
🚀 Multi-Stage Pipeline: Security testing alongside other CI/CD stages
🛡️ Customizable: Adaptable to different project security requirements

Usage Examples

🔧 Jenkins Pipeline

Quick Setup

Copy our ready-to-use template:

# Copy template
curl -O https://raw.githubusercontent.com/s4dhulabs/vimana-framework/develop/docs/pipelines/Jenkinsfile

# Commit and push
git add Jenkinsfile
git commit -m "Add Vimana security scanning pipeline"
git push

Manual Configuration

Or create your own Jenkinsfile:

pipeline {
    agent any
    
    environment {
        TARGET_URL = 'http://localhost:8000'
    }
    
    stages {
        stage('Setup Vimana') {
            steps {
                sh '''
                    curl -LsSf https://astral.sh/uv/install.sh | sh
                    source ~/.bashrc
                    uv sync
                    sudo ln -sf $PWD/vimana.py /usr/bin/vimana
                '''
            }
        }
        
        stage('Load Plugins') {
            steps {
                sh '''
                    vimana load --plugins
                    vimana list --plugins
                '''
            }
        }
        
        stage('Security Scan') {
            steps {
                sh '''
                    # Run D4M8 form fuzzing (Django Web Forms)
                    vimana run d4m8 --target-url $TARGET_URL
                    
                    # Run ViewScan for code analysis (Django Views)
                    vimana run viewscan --project-dir "${WORKSPACE}"
                '''
            }
        }
    }
    
    post {
        always {
            archiveArtifacts artifacts: 'core/_dbops_/,*.log,*.json,*.xml', fingerprint: true
        }
    }
}

Plugin Architecture

Vimana is a modular framework that works with plugins. Each plugin has specific capabilities:

D4M8: Django Web Form Fuzzer for mapping exceptions
ViewScan: Code analysis and vulnerability scanning
Other plugins: Various security testing capabilities

All plugins follow the syntax: vimana run <plugin_name> <plugin_options>

📁 Pipeline Templates

Complete pipeline templates are available in the docs/pipelines/ directory:

⚡ GitHub Actions: github-actions-basic.yml, github-actions-django.yml
🦊 GitLab CI/CD: gitlab-ci-basic.yml, gitlab-ci-django.yml
⭕ CircleCI: circleci-config.yml
🔧 Jenkins: Jenkinsfile

These templates provide production-ready configurations that can be customized for your specific needs.

📋 System Requirements

Python: 3.9 or higher
OS: Linux, macOS, Windows (WSL recommended)
Memory: Minimum 2GB RAM (4GB recommended)
Storage: 500MB free space
Network: Internet connection for initial setup

🔧 Advanced Configuration

Environment Variables

export VIMANA_CONFIG_PATH=/path/to/config
export VIMANA_LOG_LEVEL=DEBUG
export VIMANA_OUTPUT_FORMAT=json

Custom Docker Configuration

# Build with custom tag
docker build -t my-vimana:v1.0 .

# Run with custom volumes
docker run -it -v $(pwd)/data:/vf0.1/data my-vimana:v1.0

# Run with custom environment
docker run -it -e VIMANA_LOG_LEVEL=DEBUG vimana_framework:v0.1

🛠️ Troubleshooting

Common Issues

Docker Permission Denied:

sudo usermod -aG docker $USER
# Log out and back in

Python Virtual Environment Issues:

# Remove existing environment
rm -rf ~/vfe0.1
# Recreate with setup script
source scripts/setup

UV Installation Issues:

# Reinstall uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

Virtual Environment Not Active:

# If you see the default prompt instead of (vimana-framework) >
# Make sure you used 'source' not './' to run the setup script
source scripts/setup-uv

# Or manually activate the environment
source .venv/bin/activate
export VIRTUAL_ENV_DISABLE_PROMPT=1
export PS1="(vimana-framework) > "

GitHub Actions Issues:

# Check workflow logs for specific errors
# Ensure target URL is accessible from GitHub Actions
# Verify plugin dependencies are installed

Getting Help

📖 Documentation
🐛 Report Issues

🔒 Security Considerations

Always run Vimana in isolated environments
Use Docker containers for production deployments
Regularly update dependencies
Review scan results before sharing
Follow responsible disclosure practices
Only scan authorized targets
Be mindful of rate limiting and legal compliance

FilesExpand file tree

INSTALL_GUIDE.md

Latest commit

History

INSTALL_GUIDE.md

File metadata and controls

Vimana Framework v0.1 - Installation Guide

📋 Installation Quick Navigator

🎯 Recommended Paths:

🚀 Quick Start

Option 1: UV Installation (Recommended - Fastest)

🔄 Using Vimana After Installation

Option 2: Pip Installation (Traditional)

🔧 Manual Installation

🐳 Docker Installation

Option 1: Docker Compose (Recommended for development)

Option 2: Direct Docker Build

⚡ GitHub Actions Integration

Quick Setup

Automated Scanning in Your Repository

Running plugins (framewalk workflow)

⭕ CircleCI Integration

Quick Setup

Pipeline Overview

CircleCI Configuration

Pipeline Execution Flow

1. Pipeline Overview

2. Vimana Installation Process

3. Security Scanning Execution

4. Artifact Management

Key Benefits

Usage Examples

🦊 GitLab & 🔧 Jenkins Integration

🦊 GitLab CI/CD Pipeline

Quick Setup

Manual Configuration

Basic Setup - Framework Installation Only

Complete Pipeline - Django Application Security Analysis (Passive Framework Fingerprint)

Key Benefits

Usage Examples

🔧 Jenkins Pipeline

Quick Setup

Manual Configuration

Plugin Architecture

📁 Pipeline Templates

📋 System Requirements

🔧 Advanced Configuration

Environment Variables

Custom Docker Configuration

🛠️ Troubleshooting

Common Issues

Getting Help

🔒 Security Considerations