Core¶
Agent¶
client.py client side responsible for the managing clients and scan execution flow.
- class dscan.client.Agent(config)[source]¶
Bases:
object
Agent client implementation.
- do_auth()[source]¶
Initiate the authentication.
- Returns:
True if the status code of the last operation is dscan.models.structures.Status.SUCCESS False otherwise.
- Return type:
bool
- do_ready()[source]¶
This is recursive method and is responsible for, notifying the server is ready to execute a new scan, launch the scan and save the report. Until the server returns no target to scan.
Server¶
server.py server side responsible for the managing clients and scan execution flow.
- class dscan.server.AgentHandler(*args, terminate_event, context, **kwargs)[source]¶
Bases:
BaseRequestHandler
- HEADER = '<B'¶
Created when an agent connects, holds all the agents available actions. Terminates when scan targets finishes or an agent disconnects.
- property agent¶
string representation of a connection ip:port.
- Returns:
str format of agent name ip:port
- do_ready()[source]¶
After the authentication the agent notifies the server, that is ready to start scanning. This will handle the request and send a target to be scanned.
- do_report()[source]¶
When the scan the ends, the agent notifies the server that is ready to send the report. This method will handle the report transfer save the report in the reports directory and make the target as finished if the file hashes match.
- handle()[source]¶
First method to be called by BaseRequestHandler. responsible for initial call to authentication do_auth, and dispatcher, the connection is kept alive as long as agent is connected and their are targets to be delivered.
- property is_connected¶
Check if the client is still connected, the terminate event has not been set and all stages are finished or not.
- Returns:
True if the client has disconnected or the terminate event has been triggered, else False
- Return type:
bool
- class dscan.server.DScanServer(*args, options, **kwargs)[source]¶
Bases:
ThreadingMixIn
,TCPServer
Foundation of the Server. Implements the shutdown with threading.Event, and ssl configurations. and injects threading.Event to the RequestHandlerClass
- allow_reuse_address = True¶
- daemon_threads = True¶
- finish_request(request, client_address) BaseRequestHandler [source]¶
Finish one request by instantiating RequestHandlerClass.
- Returns:
RequestHandlerClass
- Return type:
´RequestHandlerClass´
- get_request() tuple [source]¶
Used to add ssl support.
- Returns:
returns a ssl.wrap_socket
- Return type:
´ssl.wrap_socket´
- property secret_key¶
- Returns:
str secret key generated in the config based on the certificate
Output¶
out.py Display the information and status.
- class dscan.out.ContextDisplay(context)[source]¶
Bases:
Display
Context is displayed as a table.
- ACTIVE_STAGES_HEADERS = ['Stage', 'Nº Targets', 'Nº Finished', 'Completion %']¶
- STAGES_HEADERS = ['Nº Stages', 'Nº Pending Tasks', 'Completion %']¶
- TASK_HEADERS = ['Agent', 'Stage', 'Task Status', 'Target Ip']¶
- class dscan.out.Display[source]¶
Bases:
object
Visualisation of the current execution status.
- CLEAR_CURRENT_LINE = '\x1b[1K\x1b[0G'¶
- CLEAR_SCREEN = '\x1b[H\x1b[2J\x1b[3J'¶
- TITLE = 'Distributed Scan Status'¶
- inline(message)[source]¶
- Parameters:
message – string message to print underneath the table printer.
Models Parsers¶
parsers.py parsers models, input ip address list collapse, or scanner results to parse.
- class dscan.models.parsers.ReportsParser(reports_path, pattern)[source]¶
Bases:
object
XML Nmap results parser.
Models Scanner¶
scanner.py scanner runtime models
- class dscan.models.scanner.Config(config, options)[source]¶
Bases:
object
Runtime configurations
- BASE = ('base', 'reports')¶
- SSL_CERTS = ('certs', 'sslcert', 'sslkey', 'ciphers', 'cert-hostname')¶
- class dscan.models.scanner.Context(options)[source]¶
Bases:
object
Context is a thread safe proxy like class, responsible for all the execution flow and inherent logic. Acts as a proxy between the active stages and the stage implementation.
- active_stages_status()[source]¶
- Returns:
list of tuples with active stages status.
- Return type:
list of tuples
- completed(agent)[source]¶
Marks a agent task as complete.
- Parameters:
agent (str) – ip:port of agent
- classmethod create(options)[source]¶
- Parameters:
options (´ServerConfig´) – instance of ServerConfig
- Returns:
instance of Context
- Return type:
´Context`
- downloading(agent)[source]¶
Marks a agent task as Downloading, notifying that the report download has started.
- Parameters:
agent (str) – ip:port of agent
- get_report(agent, file_name)[source]¶
- Parameters:
agent (str) – str with ipaddress and port in ip:port format
file_name (str) – name of the file sent by the agent.
- Returns:
file descriptor to save the scan report.
- interrupted(agent)[source]¶
Marks a task as interrupted, when agent disconnects for example.
- Parameters:
agent (str) – ip:port of agent
- property is_finished¶
- Returns:
bool iterates the active stages and collects all the finished properties, returns True if all of them are true.
- pop(agent)[source]¶
Gets the next Task from the current Active Stage, if their are no pending Tasks to be executed. Pending tasks are tasks that are canceled or restored from a previous interrupted session. If a stage is finished (no more targets), the next stage will take another stage from the list until its finished.
- Parameters:
agent – str with ipaddress and port in ip:port format, this allows the server to manage multiple agents in one host. to run multiple clients at once.
- Returns:
A target to scan! task
- Return type:
tuple
- class dscan.models.scanner.DiscoveryStage(targets_path, options, outdir, ltargets_path)[source]¶
Bases:
Stage
- class dscan.models.scanner.File(path)[source]¶
Bases:
object
Creates a stateful file object allows file to restore its previous state.
- class dscan.models.scanner.STATUS(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶
Bases:
Enum
Each Scan task has the following states: - Scheduled: the default state set when its created. - Running: Set after the agent has confirmed the task has started executing. - Interrupted: Set when the task is aborted by agent, or the server has been halted. - Downloading: Set when the agent notifies its ready to sent the report. - Completed: Set only after the report has been received successfully
- COMPLETED = 5¶
- DOWNLOADING = 4¶
- INTERRUPTED = 3¶
- RUNNING = 2¶
- SCHEDULED = 1¶
- class dscan.models.scanner.ScanProcess(output)[source]¶
Bases:
object
Used by the agent (client side), its a proxy class to provide an interface to interact with libnmap responsible for the actual execution. Its implementation allows handling, duplicate file names, with numeric prefix, as well as keeping status on the execution process.
- TASK_HEADERS = ['Target', 'Nª completed Scans', 'Status']¶
- report_name(extension)[source]¶
Checks if a report with the current target.extension exists, and prepends a number if it does.
- Parameters:
extension – xml, nmap.
- Returns:
path str path and filename, the filename will be prefixed, by a number if the base+extension already exists in the outdir.
- Return type:
str
- class dscan.models.scanner.ServerConfig(config, options, outdir)[source]¶
Bases:
object
Server configuration parser.
- SCAN_CONF = 'nmap-scan'¶
- SERVER = ('server', 'stats', 'targets', 'live-targets', 'trace')¶
- class dscan.models.scanner.Stage(stage_name, targets_path, options, outdir)[source]¶
Bases:
object
- as_tuple()[source]¶
Returns the information as tuple, nlines, finished targets and %, used by Display to print scanner status.
- Returns:
tuple of strings.
- Return type:
tuple of str.
- property isfinished¶
- Returns True if the number of lines is equal to the number of
finished targets.
- Returns:
bool
- Return type:
bool
- property percentage¶
Calculates the completion of this stage.
- Returns:
float of of the % completion.
- Return type:
float
- class dscan.models.scanner.Task(stage_name, options, target)[source]¶
Bases:
object
Representation of a scan task. A scan task is sent to an agent with a target and, scan options. Each task has the following states: - Scheduled: the default state set when its created. - Running: Set after the agent has confirmed the task has started executing. - Interrupted: Set when the task is aborted by agent, or the server has been halted. - Downloading: Set when the agent notifies its ready to sent the report. - Completed: Set only after the report has been received successfully.
Models Structures¶
structures.py network elements of the scanner
- class dscan.models.structures.Auth(*args, sock=None)[source]¶
Bases:
Structure
Authentication Request from an Agent to server!
- data¶
- op_code = 1¶
- class dscan.models.structures.Command(*args, sock=None)[source]¶
Bases:
Structure
Scan task information ! Send by the server to the agent. final format is <BB?s?s
- op_code = 3¶
- options¶
- target¶
- class dscan.models.structures.ExitStatus(*args, sock=None)[source]¶
Bases:
Structure
Scan Result Status ! Send both server and agent to signal the exit status of a operation. final format is <BB
- op_code = 4¶
- status¶
- class dscan.models.structures.Operations(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶
Bases:
IntEnum
Commands available!
- AUTH = 1¶
- COMMAND = 3¶
- READY = 2¶
- REPORT = 5¶
- STATUS = 4¶
- class dscan.models.structures.Ready(*args, sock=None)[source]¶
Bases:
Structure
Ready to start Scan ! Sent by an Agent to the server With the client’s current user id
- alias¶
- op_code = 2¶
- uid¶
- class dscan.models.structures.Report(*args, sock=None)[source]¶
Bases:
Structure
When an agent’s task terminates, it initiates a report transfer request
- filehash¶
- filename¶
- filesize¶
- op_code = 5¶
- class dscan.models.structures.Status(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶
Bases:
IntEnum
Code values for the response status.
- FAILED = 255¶
- FINISHED = 2¶
- SUCCESS = 0¶
- UNAUTHORIZED = 1¶
- UNFINISHED = 3¶