Stabalizatins

Author: voltsparx

lib/asrfacet_rb.rb

@@ -98,6 +98,7 @@
 require_relative "asrfacet_rb/scanner/results/scan_result"
 require_relative "asrfacet_rb/scanner/verbose_logger"
 require_relative "asrfacet_rb/scanner/probe_db"
+require_relative "asrfacet_rb/scanner/result_adapter"
 require_relative "asrfacet_rb/scanner/probes/tcp_prober"
 require_relative "asrfacet_rb/scanner/probes/udp_prober"
 require_relative "asrfacet_rb/scanner/probes/icmp_prober"

lib/asrfacet_rb/scanner/result_adapter.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+# For use only on systems you own or have explicit
+# written authorization to test.
+# SPDX-License-Identifier: Proprietary
+#
+# ASRFacet-Rb: Attack Surface Reconnaissance Framework
+# Copyright (c) 2026 voltsparx
+#
+# Author: voltsparx
+# Repository: https://github.com/voltsparx/ASRFacet-Rb
+# Contact: voltsparx@gmail.com
+# License: See LICENSE file in the project root
+#
+# This file is part of ASRFacet-Rb and is subject to the terms
+# and conditions defined in the LICENSE file.
+
+require "resolv"
+
+module ASRFacet
+  module Scanner
+    module ResultAdapter
+      module_function
+
+      def to_payload(scan_result, target:)
+        store = ASRFacet::ResultStore.new
+        Array(scan_result&.host_results).each do |host_result|
+          add_host_asset(store, host_result.host)
+          Array(host_result.ports).each do |port_result|
+            entry = {
+              host: host_result.host,
+              port: port_result.port,
+              proto: port_result.proto,
+              state: port_result.state,
+              service: port_result.service,
+              version: port_result.version,
+              extra: port_result.extra,
+              cpe: port_result.cpe,
+              banner: port_result.banner,
+              rtt: port_result.rtt,
+              retries: port_result.retries
+            }
+            category = case port_result.state
+                       when :open then :open_ports
+                       when :closed then :closed_ports
+                       else :filtered_ports
+                       end
+            store.add(category, entry)
+          end
+        end
+
+        summary = store.summary.merge(
+          hosts_total: Array(scan_result&.host_results).size,
+          hosts_up: Array(scan_result&.host_results).count(&:up),
+          total_open: scan_result&.total_open.to_i,
+          total_filtered: scan_result&.total_filtered.to_i,
+          scan_type: scan_result&.scan_type.to_s
+        )
+
+        {
+          store: store,
+          top_assets: [],
+          summary: summary,
+          scan_result: scan_result&.to_h,
+          execution: { stages: [], failures: [], integrity: { status: "ok", summary: "Scanner run completed.", issues: [], recommendations: [] } },
+          meta: { target: target.to_s }
+        }
+      end
+
+      def add_host_asset(store, host)
+        if ip_address?(host)
+          store.add(:ips, host)
+        else
+          store.add(:subdomains, host)
+        end
+      rescue StandardError
+        nil
+      end
+
+      def ip_address?(host)
+        Resolv::IPv4::Regex.match?(host.to_s) || Resolv::IPv6::Regex.match?(host.to_s)
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

lib/asrfacet_rb/ui/cli.rb

@@ -182,19 +182,20 @@ class << self
         def start(given_args = ARGV, config = {})
           args = Array(given_args).dup
           ASRFacet::UI::FirstRunGuide.maybe_print(args)
-          if args.delete("--console") || args.delete("-C")
+          explicit_command = args.first.to_s.match?(/\A[^-]/)
+          if !explicit_command && (args.delete("--console") || args.delete("-C"))
             return super(["console", *args], config)
           end
-          if args.delete("--web-session")
+          if !explicit_command && args.delete("--web-session")
             return super(["web", *args], config)
           end
-          if args.delete("--about")
+          if !explicit_command && args.delete("--about")
             return super(["about", *args], config)
           end
-          if args.delete("--version")
+          if !explicit_command && args.delete("--version")
             return super(["version", *args], config)
           end
-          if (index = args.index("--explain"))
+          if !explicit_command && (index = args.index("--explain"))
             topic = args[index + 1].to_s
             args.slice!(index, 2)
             return super(["explain", topic, *args], config)
@@ -258,13 +259,16 @@ def passive(domain)
       def ports(host)
         return unless ensure_framework_ready!
 
-        store = ASRFacet::ResultStore.new
-        ASRFacet::Core::ThreadSafe.print_status("Starting focused port discovery against #{host}") if options[:verbose]
-        ASRFacet::Engines::PortEngine.new.scan(host, options[:ports] || "top100", workers: options[:threads]).each do |entry|
-          store.add(:open_ports, entry)
-          announce_event(:open_port, entry.merge(host: host)) if options[:verbose]
-        end
-        output_results({ store: store, top_assets: [], summary: store.summary }, host)
+        scan_result = ASRFacet::Scanner::ScanEngine.new(
+          scan_type: "connect",
+          timing: 3,
+          verbosity: options[:verbose] ? 1 : 0,
+          version_detection: false,
+          os_detection: false,
+          version_intensity: 7,
+          ports: options[:ports] || "top100"
+        ).scan(host)
+        output_results(ASRFacet::Scanner::ResultAdapter.to_payload(scan_result, target: host), host)
       rescue ASRFacet::Error => e
         report_exception("ports", e)
       end
@@ -280,23 +284,16 @@ def ports(host)
       def portscan(target)
         return unless ensure_framework_ready!
 
-        engine = ASRFacet::Scanner::ScanEngine.new(
+        scan_result = ASRFacet::Scanner::ScanEngine.new(
           scan_type: options[:type],
           timing: options[:timing],
           verbosity: options[:verbosity],
           version_detection: options[:version],
           os_detection: options[:os],
           version_intensity: options[:intensity],
           ports: options[:ports]
-        )
-        result = engine.scan(target)
-        payload = JSON.pretty_generate(result.to_h)
-        if options[:output].to_s.empty?
-          puts(payload) if options[:format].to_s == "json"
-        else
-          File.write(options[:output], payload)
-          puts(options[:output])
-        end
+        ).scan(target)
+        output_results(ASRFacet::Scanner::ResultAdapter.to_payload(scan_result, target: target), target)
       rescue ASRFacet::Error => e
         report_exception("portscan", e)
       end

lib/asrfacet_rb/ui/help_catalog.rb

@@ -47,14 +47,26 @@ module HelpCatalog
           summary: "Run a focused TCP port scan against a host or IP.",
           usage: "asrfacet-rb ports HOST [--ports top100|top1000|1-1000|80,443]",
           details: [
-            "Use this command when you only need network exposure and service banners.",
+            "Use this command when you only need a quick connectivity pass through the scanner engine without version or OS fingerprinting.",
             "The port selector accepts named ranges, numeric ranges, or comma-separated custom lists."
           ],
           examples: [
             "asrfacet-rb ports 192.0.2.10",
             "asrfacet-rb ports app.example.com --ports 22,80,443,8080"
           ]
         },
+        "portscan" => {
+          summary: "Run the full scanner engine directly with explicit scan type, timing, and optional fingerprinting.",
+          usage: "asrfacet-rb portscan TARGET --type connect|syn|udp|ack|fin|null|xmas|window|maimon|ping|service [--timing 0-5] [--version] [--os]",
+          details: [
+            "Use this command when you want direct control over the scanner engine instead of the simpler `ports` wrapper.",
+            "Timing templates mirror the scanner timing profiles and the command can also render PDF, DOCX, CSV, JSON, HTML, TXT, CLI, ALL, or SARIF output."
+          ],
+          examples: [
+            "asrfacet-rb portscan 192.0.2.10 --type syn --timing 4 --ports 1-1024",
+            "asrfacet-rb portscan app.example.com --type service --version --intensity 9 --format json"
+          ]
+        },
         "dns" => {
           summary: "Collect DNS records for a domain without running the full pipeline.",
           usage: "asrfacet-rb dns DOMAIN [--format cli|json|html|txt]",
@@ -121,7 +133,7 @@ module HelpCatalog
           details: [
             "Web session mode starts a local-only dashboard for recon planning, saved sessions, run history, report browsing, and live stage updates.",
             "Session drafts are autosaved to disk so configuration survives accidental browser closes, process crashes, and power loss.",
-            "The dashboard uses the same pipeline, memory, monitoring, headless, webhook, and rate-control options as the CLI."
+            "The dashboard uses the same pipeline, scanner engine, memory, monitoring, headless, webhook, rate-control, and multi-format reporting options as the CLI."
           ],
           examples: [
             "asrfacet-rb --web-session",
@@ -133,13 +145,14 @@ module HelpCatalog
           usage: "--format cli|json|html|txt and --output PATH",
           details: [
             "CLI output prints directly to the terminal and is best for quick inspection.",
-            "JSON is best for scripting, HTML is best for sharing a styled offline report, and TXT is a plain-text export.",
+            "JSON and SARIF are best for scripting, HTML and PDF are best for polished sharing, DOCX is best for editable handoff, TXT is a plain-text export, and CSV creates flat data slices.",
             "ASRFacet-Rb also stores a full report bundle automatically under ~/.asrfacet_rb/output/reports/<target>/<timestamp>/ so installed users can find earlier runs easily.",
-            "Use `--output` when you want an additional custom file path alongside the stored report bundle."
+            "Use `--output` when you want an additional custom file path alongside the stored report bundle. Use `--format all` when you want the framework to emit every supported report flavor in one request."
           ],
           examples: [
             "asrfacet-rb scan example.com --format html --output report.html",
-            "asrfacet-rb passive example.com --format json --output passive.json"
+            "asrfacet-rb passive example.com --format json --output passive.json",
+            "asrfacet-rb portscan 192.0.2.10 --format pdf --output service-map.pdf"
           ]
         },
         "scope" => {
@@ -465,6 +478,7 @@ def menu(executable: PRIMARY_EXECUTABLE)
           "  scan DOMAIN        Full reconnaissance pipeline        Aliases: s, sc",
           "  passive DOMAIN     Passive subdomain discovery only    Aliases: p, pa",
           "  ports HOST         Focused TCP port scan               Aliases: pt, po",
+          "  portscan TARGET    Direct scanner engine control       Aliases: none",
           "  dns DOMAIN         DNS record collection only          Aliases: d, dn",
           "  lab                Start the local validation lab      Aliases: none",
           "  interactive        Guided beginner workflow            Aliases: i, int",
@@ -478,7 +492,7 @@ def menu(executable: PRIMARY_EXECUTABLE)
           "",
           "Global options:",
           "  -o, --output PATH  Save output to a file instead of printing",
-          "  -f, --format TYPE  cli, json, html, or txt",
+          "  -f, --format TYPE  cli, json, html, txt, csv, pdf, docx, all, or sarif",
           "  -v, --verbose      Print stage-by-stage status messages",
           "  -t, --threads N    Worker concurrency for threaded engines",
           "      --timeout SEC  Network timeout for active requests",
@@ -503,6 +517,7 @@ def menu(executable: PRIMARY_EXECUTABLE)
           "  #{executable} scan example.com --ports top1000 --format html --output report.html",
           "  #{executable} passive example.com --format json",
           "  #{executable} ports api.example.com --ports 80,443,8443",
+          "  #{executable} portscan 192.0.2.10 --type syn --timing 4 --ports 1-1024",
           "  #{executable} lab",
           "  #{executable} about",
           "  #{executable} help scan",

lib/asrfacet_rb/ui/interactive.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
+# For use only on systems you own or have explicit
+# written authorization to test.
 # SPDX-License-Identifier: Proprietary
 #
 # ASRFacet-Rb: Attack Surface Reconnaissance Framework
@@ -25,25 +27,48 @@ def initialize(prompt: TTY::Prompt.new)
 
       def start
         target = @prompt.ask("Target domain:") { |q| q.required(true) }
-        mode = @prompt.select("Scan mode:", ["Full", "Passive", "Ports", "DNS"])
+        mode = @prompt.select("Scan mode:", ["Full", "Passive", "Ports", "Portscan", "DNS"])
         port_range = nil
-        if %w[Full Ports].include?(mode)
+        scan_type = "connect"
+        timing = 3
+        version_detection = false
+        os_detection = false
+        intensity = 7
+        if %w[Full Ports Portscan].include?(mode)
           port_choice = @prompt.select("Port range:", ["Top100", "Top1000", "Custom"])
           port_range = port_choice == "Custom" ? @prompt.ask("Custom port range:") : port_choice.downcase
         end
+        if mode == "Portscan"
+          scan_type = @prompt.select("Scan type:", %w[connect syn udp ack fin null xmas window maimon ping service])
+          timing = @prompt.select("Timing template:", (0..5).to_a)
+          version_detection = @prompt.yes?("Enable version detection?")
+          os_detection = @prompt.yes?("Enable OS detection?")
+          intensity = @prompt.select("Version intensity:", (0..9).to_a) if version_detection
+        end
         output_format = @prompt.select("Output format:", ["CLI", "JSON", "HTML", "TXT"]).downcase
         shodan_key = @prompt.yes?("Add a Shodan key?") ? @prompt.mask("Shodan API key:") : nil
 
         summary = [
           "Target: #{target}",
           "Mode: #{mode}",
           "Ports: #{port_range || 'n/a'}",
+          "Scan type: #{mode == 'Portscan' ? scan_type : 'n/a'}",
           "Format: #{output_format}",
           "Shodan: #{shodan_key.to_s.empty? ? 'no' : 'yes'}"
         ].join(" | ")
         return nil unless @prompt.yes?("Run scan? #{summary}")
 
-        result = run_with_spinners(target, mode, port_range, shodan_key)
+        result = run_with_spinners(
+          target,
+          mode,
+          port_range,
+          shodan_key,
+          scan_type: scan_type,
+          timing: timing,
+          version_detection: version_detection,
+          os_detection: os_detection,
+          intensity: intensity
+        )
         render_output(result, output_format)
       rescue StandardError => e
         ASRFacet::Core::ThreadSafe.print_error(e.message)
@@ -52,7 +77,7 @@ def start
 
       private
 
-      def run_with_spinners(target, mode, port_range, shodan_key)
+      def run_with_spinners(target, mode, port_range, shodan_key, scan_type:, timing:, version_detection:, os_detection:, intensity:)
         case mode
         when "Full"
           dashboard = ASRFacet::ProgressDashboard.new
@@ -81,12 +106,30 @@ def run_with_spinners(target, mode, port_range, shodan_key)
           { store: store, top_assets: [] }
         when "Ports"
           ASRFacet::Core::ThreadSafe.print_status("Running port scan")
-          store = ASRFacet::ResultStore.new
-          ASRFacet::Engines::PortEngine.new.scan(target, port_range || "top100").each do |entry|
-            store.add(:open_ports, entry)
-          end
+          scan_result = ASRFacet::Scanner::ScanEngine.new(
+            scan_type: :connect,
+            timing: 3,
+            verbosity: 0,
+            version_detection: false,
+            os_detection: false,
+            version_intensity: 7,
+            ports: port_range || "top100"
+          ).scan(target)
           ASRFacet::Core::ThreadSafe.print_good("Port scan complete")
-          { store: store, top_assets: [] }
+          ASRFacet::Scanner::ResultAdapter.to_payload(scan_result, target: target)
+        when "Portscan"
+          ASRFacet::Core::ThreadSafe.print_status("Running scanner engine")
+          scan_result = ASRFacet::Scanner::ScanEngine.new(
+            scan_type: scan_type,
+            timing: timing,
+            verbosity: 0,
+            version_detection: version_detection,
+            os_detection: os_detection,
+            version_intensity: intensity,
+            ports: port_range || "top100"
+          ).scan(target)
+          ASRFacet::Core::ThreadSafe.print_good("Scanner engine complete")
+          ASRFacet::Scanner::ResultAdapter.to_payload(scan_result, target: target)
         else
           ASRFacet::Core::ThreadSafe.print_status("Collecting DNS records")
           store = ASRFacet::ResultStore.new