ASRFacet-Rb

ASRFacet-Rb is a Ruby 3.2+ framework for authorized attack surface reconnaissance.
It is built for repeatable workflows, relationship-aware intelligence, and run-to-run change tracking, not one-off scanner output.

Project website: https://voltsparx.github.io/ASRFacet-Rb/

Quick Navigation

• What It Solves
• Architecture and Process Flow
• Installation Guide
• Usage Guide with Examples
• Output, Storage, and Reporting
• Testing and Release Verification
• Troubleshooting Guide
• Documentation Map

What It Solves

Most recon tools are optimized for snapshots. That often creates:

• Scattered results across separate tools and files
• Weak run-to-run comparability
• Lost relationships between hosts, IPs, ports, services, and findings

ASRFacet-Rb addresses this with pipeline stages, memory-backed tracking, and structured output.

Architecture and Process Flow

Execution Roles

Layer	Responsibility
Scheduler	Decides what runs next
Engines	Execute bounded tasks
Investigator	Reacts to significant findings
Fusion/Store	Persists and correlates results

Pipeline Visualization

flowchart LR
    A[Passive Discovery] --> B[Active Validation]
    B --> C[Service and Web Mapping]
    C --> D[Correlation Engine]
    D --> E[Tracking and Change Summary]

Loading

Stage Intent

Stage	Main Outcome
Passive Discovery	Candidate assets from low-noise sources
Active Validation	Confirmed hosts, IPs, open ports, and HTTP surfaces
Service/Web Mapping	Reachable application/service context
Correlation Engine	Relationship mapping and prioritization
Tracking Engine	Delta detection and historical visibility

Installation Guide

Requirements

• Ruby >= 3.2
• Bundler
• Explicit permission to test targets

Installation Paths at a Glance

Path	Use Case
bundle exec from repo	Development and contribution
install/*.sh / install/windows.ps1	Managed local system install
Website installers (docs/website/web_assets/installers)	Download-first install flow

30-Second Quick Start (Repo Mode)

git clone https://github.com/voltsparx/ASRFacet-Rb.git
cd ASRFacet-Rb
bundle install
bundle exec rake
bundle exec ruby bin/asrfacet-rb scan example.com --passive-only

Managed Installer Modes

Mode	Description
install	Install framework and launchers
test	Repo-local smoke install
update	Refresh managed install
uninstall	Remove managed install and launchers

Installed command aliases:

• asrfacet-rb
• asrfrb

Installer prompt theme:

• [ASRFacet-Rb][INFO]
• [ASRFacet-Rb][ OK ]
• [ASRFacet-Rb][WARN]
• [ASRFacet-Rb][FAIL]

Usage Guide with Examples

Core Commands

Command	Purpose	Example
scan DOMAIN	Full pipeline	asrfacet-rb scan example.com
passive DOMAIN	Passive-only discovery	asrfacet-rb passive example.com
ports HOST	Focused port validation	asrfacet-rb ports api.example.com --ports top1000
dns DOMAIN	DNS-focused collection	asrfacet-rb dns example.com
--console	Interactive shell mode	asrfacet-rb --console
--web-session	Local web control panel	asrfacet-rb --web-session
about	Framework overview	asrfacet-rb about
--explain TOPIC	Built-in topic guidance	asrfacet-rb --explain scope

Guided Workflow 1: Passive First

asrfacet-rb passive example.com --format json --output passive.json
asrfacet-rb dns example.com
asrfacet-rb ports example.com --ports top100

When to use: low-noise recon kickoff with manual expansion.

Guided Workflow 2: Full Report Bundle

asrfacet-rb scan example.com --monitor --memory --format html --output report.html

When to use: recurring assessments where historical deltas matter.

Guided Workflow 3: Web Session and Operator UX

asrfacet-rb --web-session

When to use: visual control panel flow for recon, mapping, and report access.

Output, Storage, and Reporting

Output Formats

Format	Best For
cli	Live operator feedback
txt	Plain-text sharing
html	Human-friendly reports with richer structure
json	Automation and downstream tooling

Storage Layout

Path	Data
~/.asrfacet_rb/output/	Report bundles and streams
~/.asrfacet_rb/memory/	Recon memory and deltas
~/.asrfacet_rb/web_sessions/	Saved web session state

Reporting Process Visualization

flowchart TD
    A[Scan Run] --> B[Result Store]
    B --> C[CLI/TXT/HTML/JSON Formatters]
    C --> D[Report Bundle Saved]
    D --> E[Recon Memory Updated]
    E --> F[Change Summary Available]

Loading

Testing and Release Verification

bundle exec rake
bundle exec rake spec
bundle exec rake test:cli
bundle exec rake test:web
bundle exec rake test:lab
bundle exec rake test:install
bundle exec rake test:website_installers

Verification snapshot:

• Date: 2026-04-09
• Result: 53 examples, 0 failures
• Full verify gate: bundle exec rake passed

Troubleshooting Guide

Symptom	Likely Cause	Quick Fix
bundle command missing	Bundler not installed	gem install bundler
Installer exits on permission/path	Existing unmanaged target path	Remove/rename conflicting path or use managed location
Noisy or slow run	Too many threads or broad scope	Lower --threads, tighten --scope, use passive-first flow
Report confusion	Multiple formats generated	Start with report.html then inspect report.json for automation
Web mode not reachable	Host/port mismatch	Start with --web-host 127.0.0.1 --web-port 4567 and retry

Trust Signals

• Version file: VERSION
• Changelog: CHANGELOG.md
• Roadmap: ROADMAP.md
• Website docs: https://voltsparx.github.io/ASRFacet-Rb/

Documentation Map

• docs/getting-started.md
• docs/architecture.md
• docs/web-session.md
• docs/reporting.md
• docs/lab.md
• docs/publishing.md

Authorized Use

Use ASRFacet-Rb only on systems you own or have explicit written permission to test.

License

Proprietary custom license. See LICENSE.

Author

• Handle: voltsparx
• Email: voltsparx@gmail.com
• Repository: https://github.com/voltsparx/ASRFacet-Rb