API Integration

Overview

Scan4all provides a programmatic API that allows you to integrate its scanning capabilities into your own Go applications. The API is located in lib/api/main.go and provides a simple interface for triggering scans.

Quick Start

Import the Package

import (
    "github.com/GhostTroops/scan4all/lib/api"
)

Basic Scan

package main

import (
    "github.com/GhostTroops/scan4all/lib/api"
)

func main() {
    // Start a scan with default options
    api.StartScan(nil)
}

Scan with Custom Options

package main

import (
    "github.com/GhostTroops/scan4all/lib/api"
)

func main() {
    options := &map[string]interface{}{
        "Host":              "192.168.1.1/24",
        "Ports":             "80,443,8080",
        "Output":            "results.json",
        "JSON":              true,
        "Verbose":           true,
        "EnableProgressBar": true,
    }
    
    api.StartScan(options)
}

API Reference

StartScan Function

The main entry point for programmatic scanning:

func StartScan(oOpts *map[string]interface{})

Parameters:

oOpts: Optional map of configuration options that override default settings

Example:

options := &map[string]interface{}{
    "Host":    "example.com",
    "Ports":   "1-65535",
    "Verbose": true,
}

api.StartScan(options)

Configuration Options

The following options can be passed to StartScan:

Target Options

Option	Type	Description	Example
`Host`	string	Single target host	`"192.168.1.1"`
`HostsFile`	string	File containing target list	`"targets.txt"`
`List`	string	Comma-separated target list	`"192.168.1.1,example.com"`
`Ports`	string	Ports to scan	`"80,443,8080-8090"`

Scan Options

Option	Type	Description	Default
`Output`	string	Output file path	`""`
`JSON`	bool	Output in JSON format	`false`
`Verbose`	bool	Verbose output	`false`
`Debug`	bool	Debug mode	`false`
`Silent`	bool	Silent mode	`false`
`EnableProgressBar`	bool	Show progress bar	`false`
`NoColor`	bool	Disable colored output	`false`

Advanced Options

Option	Type	Description
`priorityNmap`	bool	Use nmap for scanning
`noScan`	bool	Skip port scan, use existing results
`enableNuclei`	bool	Enable Nuclei scanning
`UrlPrecise`	bool	Precise URL scanning

Advanced Usage

Scanning Multiple Targets

package main

import (
    "github.com/GhostTroops/scan4all/lib/api"
)

func main() {
    targets := []string{
        "192.168.1.1",
        "example.com",
        "10.0.0.0/24",
    }
    
    for _, target := range targets {
        options := &map[string]interface{}{
            "Host":    target,
            "Output":  target + "-results.json",
            "JSON":    true,
            "Verbose": false,
        }
        
        api.StartScan(options)
    }
}

Port-Specific Scanning

func scanWebServices() {
    options := &map[string]interface{}{
        "Host":          "192.168.1.0/24",
        "Ports":         "80,443,8080,8443",
        "Output":        "web-services.json",
        "JSON":          true,
        "priorityNmap":  false, // Use naabu for faster scanning
    }
    
    api.StartScan(options)
}

Using Nmap Results

func scanFromNmapResults() {
    options := &map[string]interface{}{
        "HostsFile": "nmap-results.xml",
        "noScan":    true,  // Skip port scan, process existing results
        "Output":    "analysis.json",
        "JSON":      true,
    }
    
    api.StartScan(options)
}

Working with Results

Result Storage

Scan results are stored in multiple formats:

File Output - Specified via Output option
Elasticsearch - If configured in config/config.json
In-memory - Accessible via global variables

Accessing Results in Code

import (
    "github.com/GhostTroops/scan4all/lib/util"
)

func processResults() {
    // Access global options
    outputFile := util.Output
    verbose := util.G_Options["Verbose"].(bool)
    
    // Read results from output file
    // ... your processing logic
}

Integration Patterns

Web Service Integration

package main

import (
    "encoding/json"
    "net/http"
    "github.com/GhostTroops/scan4all/lib/api"
)

type ScanRequest struct {
    Target  string   `json:"target"`
    Ports   string   `json:"ports"`
    Verbose bool     `json:"verbose"`
}

func handleScanRequest(w http.ResponseWriter, r *http.Request) {
    var req ScanRequest
    json.NewDecoder(r.Body).Decode(&req)
    
    options := &map[string]interface{}{
        "Host":    req.Target,
        "Ports":   req.Ports,
        "Verbose": req.Verbose,
        "JSON":    true,
        "Output":  "/tmp/scan-" + req.Target + ".json",
    }
    
    // Run scan asynchronously
    go api.StartScan(options)
    
    w.WriteHeader(http.StatusAccepted)
    json.NewEncoder(w).Encode(map[string]string{
        "status": "Scan started",
        "target": req.Target,
    })
}

func main() {
    http.HandleFunc("/scan", handleScanRequest)
    http.ListenAndServe(":8080", nil)
}

CI/CD Pipeline Integration

package main

import (
    "fmt"
    "os"
    "github.com/GhostTroops/scan4all/lib/api"
)

func main() {
    // Get target from environment
    target := os.Getenv("SCAN_TARGET")
    if target == "" {
        fmt.Println("SCAN_TARGET environment variable not set")
        os.Exit(1)
    }
    
    options := &map[string]interface{}{
        "Host":    target,
        "Ports":   "80,443",
        "Output":  "ci-scan-results.json",
        "JSON":    true,
        "Silent":  true, // Minimal output for CI
    }
    
    api.StartScan(options)
    
    // Process results and exit with appropriate code
    // ... vulnerability threshold checking
}

Batch Scanning

package main

import (
    "bufio"
    "os"
    "sync"
    "github.com/GhostTroops/scan4all/lib/api"
)

func batchScan(targetsFile string, maxConcurrent int) {
    file, _ := os.Open(targetsFile)
    defer file.Close()
    
    var wg sync.WaitGroup
    semaphore := make(chan struct{}, maxConcurrent)
    
    scanner := bufio.NewScanner(file)
    for scanner.Scan() {
        target := scanner.Text()
        
        wg.Add(1)
        semaphore <- struct{}{} // Acquire
        
        go func(t string) {
            defer wg.Done()
            defer func() { <-semaphore }() // Release
            
            options := &map[string]interface{}{
                "Host":   t,
                "Output": t + "-results.json",
                "JSON":   true,
                "Silent": true,
            }
            
            api.StartScan(options)
        }(target)
    }
    
    wg.Wait()
}

func main() {
    batchScan("targets.txt", 5) // 5 concurrent scans
}

Environment Variables

Many options can be controlled via environment variables:

import "os"

// Set before calling StartScan
os.Setenv("priorityNmap", "false")
os.Setenv("noScan", "true")
os.Setenv("EnableSubfinder", "true")
os.Setenv("EnableHoneyportDetection", "true")
os.Setenv("UrlPrecise", "true")
os.Setenv("PPSSWWDD", "rootPassword") // For nmap

api.StartScan(options)

Error Handling

import (
    "log"
    "github.com/GhostTroops/scan4all/lib/api"
)

func safeScan(target string) {
    defer func() {
        if r := recover(); r != nil {
            log.Printf("Scan panic recovered: %v", r)
        }
    }()
    
    options := &map[string]interface{}{
        "Host":   target,
        "Debug":  true, // Enable debug for error details
    }
    
    api.StartScan(options)
}

Performance Considerations

Thread Pool Management

The default thread pool size is 5000. Adjust based on your system resources:

import "os"

// Set before scanning
os.Setenv("ScanPoolSize", "10000")

Memory Management

For large-scale scans, consider:

Processing targets in batches
Using Silent mode to reduce memory usage
Enabling Elasticsearch for result storage
Clearing result files periodically

Network Optimization

options := &map[string]interface{}{
    "Host":         "target.com",
    "priorityNmap": false,  // Use naabu for faster scanning
    "Ports":        "80,443", // Limit port range
}

Configuration Files

Loading Custom Config

Scan4all loads configuration from config/config.json. You can customize:

{
  "ScanPoolSize": 5000,
  "EnableSubfinder": false,
  "EnableHoneyportDetection": false,
  "nuclei": {
    "enable": true,
    "templates": ["/path/to/templates"]
  }
}

Integration Examples

Complete Example

package main

import (
    "fmt"
    "github.com/GhostTroops/scan4all/lib/api"
)

func main() {
    opts := &map[string]interface{}{
        "Host":              "example.com",
        "Ports":             "1-1000",
        "Output":            "results.json",
        "JSON":              true,
        "Verbose":           true,
        "EnableProgressBar": true,
    }
    
    fmt.Println("Starting scan...")
    api.StartScan(opts)
    fmt.Println("Scan complete!")
}

Async Scanning

package main

import (
    "sync"
    "github.com/GhostTroops/scan4all/lib/api"
)

func asyncScan(targets []string) {
    var wg sync.WaitGroup
    
    for _, target := range targets {
        wg.Add(1)
        go func(t string) {
            defer wg.Done()
            
            opts := &map[string]interface{}{
                "Host":   t,
                "Silent": true,
            }
            api.StartScan(opts)
        }(target)
    }
    
    wg.Wait()
}

Advanced Topics

Development

Best Practices

Overview

Quick Start

Import the Package

Basic Scan

Scan with Custom Options

API Reference

StartScan Function

Configuration Options

Target Options

Scan Options

Advanced Options

Advanced Usage

Scanning Multiple Targets

Port-Specific Scanning

Using Nmap Results

Working with Results

Result Storage

Accessing Results in Code

Integration Patterns

Web Service Integration

CI/CD Pipeline Integration

Batch Scanning

Environment Variables

Error Handling

Performance Considerations

Configuration Files

Loading Custom Config

Integration Examples

Complete Example

Async Scanning

Next Steps

Custom Modules

Contributing

Build docs developers (and LLMs) love

Advanced Topics

Development

Best Practices

​Overview

​Quick Start

​Import the Package

​Basic Scan

​Scan with Custom Options

​API Reference

​StartScan Function

​Configuration Options

​Target Options

​Scan Options

​Advanced Options

​Advanced Usage

​Scanning Multiple Targets

​Port-Specific Scanning

​Using Nmap Results

​Working with Results

​Result Storage

​Accessing Results in Code

​Integration Patterns

​Web Service Integration

​CI/CD Pipeline Integration

​Batch Scanning

​Environment Variables

​Error Handling

​Performance Considerations

​Configuration Files

​Loading Custom Config

​Integration Examples

Complete Example

Async Scanning

​Next Steps

Custom Modules

Contributing

Build docs developers (and LLMs) love

Overview

Quick Start

Import the Package

Basic Scan

Scan with Custom Options

API Reference

StartScan Function

Configuration Options

Target Options

Scan Options

Advanced Options

Advanced Usage

Scanning Multiple Targets

Port-Specific Scanning

Using Nmap Results

Working with Results

Result Storage

Accessing Results in Code

Integration Patterns

Web Service Integration

CI/CD Pipeline Integration

Batch Scanning

Environment Variables

Error Handling

Performance Considerations

Configuration Files

Loading Custom Config

Integration Examples

Next Steps