AutoRecon/AUTORECON_CONTRIBUTION_GUIDE.md

AutoRecon Modular Setup System - Contribution Guide

Overview

This document outlines the modular setup system developed by neur0map for AutoRecon, providing comprehensive installation, management, and maintenance capabilities across multiple operating systems. The system consists of a Makefile and supporting shell scripts that automate the entire AutoRecon setup process.

System Architecture

Core Components

Makefile (Entry Point)
├── scripts/system-check.sh      (Prerequisites & OS detection)
├── scripts/detect-os.sh         (OS detection helper for Makefile)
├── scripts/install-tools.sh     (Installation router)
│   ├── scripts/install-tools-debian.sh   (Debian/Ubuntu/Kali/Parrot)
│   ├── scripts/install-tools-macos.sh    (macOS with Homebrew)
│   └── scripts/install-tools-arch.sh     (Arch Linux/Manjaro)
├── scripts/setup-python.sh      (Python environment & command setup)
├── scripts/setup-docker.sh      (Docker management)
├── scripts/update.sh            (Maintenance & updates)
└── scripts/cleanup.sh           (Complete removal)

Workflow Dependencies

make setup:
    system-check.sh → detect-os.sh → install-tools.sh → setup-python.sh

make update:
    update.sh → (git pull → python update → tools update → docker rebuild)

make clean:
    cleanup.sh → (remove venv → remove tools → remove docker → cleanup results)

Available Commands

1. Primary Setup Commands

make setup

Purpose: Complete local installation with auto-detected OS support
When to use: First-time setup or fresh installation
What it does:

• Detects operating system and prerequisites
• Installs security tools based on OS
• Sets up Python virtual environment
• Creates global autorecon command
• Provides ready-to-use AutoRecon installation

Output Example:

Setting up AutoRecon...

🔍 Checking prerequisites...
✅ Python 3.10.12 detected
✅ Detected: ubuntu

📦 Installing security tools for ubuntu (Debian-based)...
[...tool installation...]

🐍 Setting up Python environment...
📦 Installing Python dependencies...
🔧 Creating autorecon command...

✅ Setup complete!

make setup-docker

Purpose: Docker-based setup with interactive terminal
When to use:

• Non-Kali systems requiring full tool support
• Isolated/containerized environment preferred
• Local tool installation not desired

What it does:

• Builds AutoRecon Docker image
• Launches interactive container terminal
• Mounts results directory for persistence
• Provides full security toolkit in container

make clean

Purpose: Complete removal of AutoRecon installation
When to use:

• Uninstalling AutoRecon
• Starting fresh after issues
• Freeing up disk space

What it does:

• Removes Python virtual environment
• Removes installed security tools (with confirmation)
• Removes Docker images
• Removes global commands
• Cleans up temporary files

2. Maintenance Commands

make update

Purpose: Update all components to latest versions
When to use:

• Regular maintenance (weekly/monthly)
• After AutoRecon repository updates
• Before major scanning projects

What it does:

• Updates git repository with latest changes
• Updates Python packages
• Updates system security tools
• Rebuilds Docker image if needed
• Shows summary of changes

make docker-cmd

Purpose: Launch additional Docker terminal sessions
When to use:

• Multiple concurrent scanning sessions
• After make setup-docker for additional terminals

3. Help Command

make help

Purpose: Display comprehensive usage information
Contains:

• All available commands
• OS compatibility matrix
• Usage recommendations
• Docker workflow guide

Operating System Support

Tier 1: Full Support (20+ Security Tools)

• Kali Linux: Native security distribution
• Parrot OS: Security-focused distribution
• Ubuntu/Debian: Comprehensive apt-based installation
• macOS: Homebrew-based toolkit (15+ tools)

Tier 2: Basic Support

• Arch/Manjaro: Core tools only (nmap, curl, wget, git)
• Other Linux: Fallback to basic tools

Tier 3: Docker Recommended

• Windows: Use WSL + Docker
• Unsupported systems: Docker provides full functionality

Script Details

system-check.sh

Purpose: Prerequisites validation and OS detection
Exports: OS_ID, OS_ID_LIKE, WSL_DETECTED
Checks:

• Python 3.8+ availability
• Operating system identification
• WSL environment detection
• Package manager availability

install-tools.sh (Router)

Purpose: Routes to appropriate OS-specific installer
Parameters: OS_ID, OS_ID_LIKE, WSL_DETECTED
Routes to:

• install-tools-debian.sh for Debian-based systems
• install-tools-macos.sh for macOS
• install-tools-arch.sh for Arch-based systems

install-tools-debian.sh

Tools Installed:

# Core tools
curl wget git nmap nikto whatweb sslscan smbclient

# Enumeration tools  
seclists dnsrecon enum4linux feroxbuster gobuster 
impacket-scripts nbtscan onesixtyone oscanner 
redis-tools smbmap snmp sipvicious tnscmd10g

WSL Compatibility: Includes snap package fallbacks

install-tools-macos.sh

Tools Installed:

# Core network tools
nmap curl wget git gobuster nikto whatweb sslscan

# Enumeration tools
feroxbuster redis-tools smbclient

# Additional security tools  
hydra john-jumbo hashcat sqlmap exploitdb binwalk exiftool

# Python tools
impacket crackmapexec enum4linux-ng

install-tools-arch.sh

Limited Installation: Basic tools only (nmap, curl, wget, git, python)
Recommendation: Use Docker for full functionality

setup-python.sh

Functions:

• Creates Python virtual environment
• Installs requirements.txt dependencies
• Creates autorecon-cmd script
• Installs global /usr/local/bin/autorecon command
• Handles permission issues gracefully

setup-docker.sh

Functions:

• Docker availability verification
• AutoRecon image building
• Interactive container launch
• Results directory mounting
• Container session management

update.sh

Update Process:

1. Git Update: Pull latest changes, handle stashes
2. Python Update: Upgrade pip and packages
3. Tools Update: OS-appropriate tool updates
4. Docker Update: Rebuild if Dockerfile changed
5. Summary: Show what was updated

cleanup.sh

Removal Process:

1. Python Environment: Remove venv and commands
2. Security Tools: OS-specific removal (with confirmation)
3. Docker Resources: Remove images and containers
4. Results: Clean empty directories
5. Warning: Notify about active virtual environments

Usage Patterns

1. First Time Setup

# Clone AutoRecon repository
git clone https://github.com/Tib3rius/AutoRecon.git
cd AutoRecon

# Full local setup
make setup

# Test installation
autorecon --help
autorecon 127.0.0.1

2. Docker-Based Setup

# Docker setup (recommended for non-Kali)
make setup-docker

# Inside container:
autorecon --help
autorecon target.com
ls /scans  # View results

# Additional sessions
make docker-cmd

3. Regular Maintenance

# Weekly/monthly updates
make update

# Check for issues
autorecon --help

# If problems occur
make clean
make setup

4. Contributing Development

# Setup development environment
make setup

# Make changes to AutoRecon code
# ...

# Test changes
autorecon test-target

# Update after pulling latest
make update

Integration Notes for AutoRecon

Required Changes for Integration

1. Project Name References: Change all instances of "ipcrawler" to "autorecon" in:

   • setup-python.sh (command creation)
   • setup-docker.sh (image names and references)
   • cleanup.sh (removal procedures)
   • Makefile (help text and commands)

2. Global Command: Scripts create /usr/local/bin/autorecon instead of /usr/local/bin/ipcrawler

3. Docker Integration: Requires existing Dockerfile and requirements.txt in repository root

File Structure Requirements

AutoRecon/
├── Makefile
├── scripts/
│   ├── system-check.sh
│   ├── detect-os.sh  
│   ├── install-tools.sh
│   ├── install-tools-debian.sh
│   ├── install-tools-macos.sh
│   ├── install-tools-arch.sh
│   ├── setup-python.sh
│   ├── setup-docker.sh
│   ├── update.sh
│   └── cleanup.sh
├── requirements.txt
├── Dockerfile
└── autorecon.py

Benefits for AutoRecon Project

1. User Experience

• Simplified Installation: Single make setup command
• Cross-Platform: Automated OS detection and appropriate tool installation
• Maintenance: Easy updates with make update
• Cleanup: Complete removal with make clean

2. Developer Experience

• Consistent Environment: Standardized setup across contributors
• Docker Integration: Isolated development environments
• Modular Design: Easy to modify and extend
• Error Handling: Graceful failures with helpful messages

3. Documentation

• Self-Documenting: make help provides comprehensive guidance
• Status Messages: Clear feedback during installation
• OS-Specific: Tailored instructions for each platform

4. Maintenance

• Automated Updates: Handles git, Python, tools, and Docker
• Dependency Management: Ensures all components stay current
• Clean Removal: Complete uninstall capability

Contribution Guidelines

For Pull Request

1. Create feature branch from main AutoRecon repository
2. Update project references from "ipcrawler" to "autorecon"
3. Test on multiple operating systems:
   • Ubuntu/Debian
   • Kali Linux
   • macOS (with Homebrew)
   • Arch Linux
4. Verify Docker functionality
5. Update documentation as needed

Testing Checklist

• make setup works on supported OS
• make setup-docker builds and runs
• make update updates all components
• make clean removes everything
• Global autorecon command functions
• Error handling works for unsupported systems
• WSL compatibility verified

Author

Contributor: neur0map
Original Project: AutoRecon by Tib3rius
Fork: ipcrawler (source of these enhancements)

This modular setup system significantly enhances AutoRecon's accessibility and maintainability across diverse operating systems and deployment scenarios.