server package — Faraday 0.1 documentation

# server package

## Submodules

## server.utils module

A module to handle request to the Faraday Server.

Note

Before using this as an API, you should copy this file and edit the FARADAY_UP and the SERVER_URL variables found inmediatly below the imports.

FARADAY_UP should be set to False in the copy of the file, and SERVER_URL must be a valid server url.

Warning

This module was though of primarly as a way of querying and removing information from the Faraday Server. Adding objects is supported, but should be used with care, specially regarding the ID of objects, which must be always unique.

`persistence.server.server.` `get_hosts`(workspace_name, **params)

  Get hosts from the server.

  Parameters: | workspace_name (str) – the workspace from which to get the hosts. **params – any of valid request parameters for CouchDB.
  Returns: | A dictionary containing the hosts matching the query.

`persistence.server.server.` `get_all_vulns`(workspace_name, **params)

  Get vulns, both normal and web, from the server.

  Parameters: | workspace_name (str) – the workspace from which to get the vulns. **params – any of valid request parameters for CouchDB.
  Returns: | A dictionary containing the vulns matching the query.

`persistence.server.server.` `get_vulns`(workspace_name, **params)

  Get only normal vulns from the server.

  Parameters: | workspace_name (str) – the workspace from which to get the vulns. **params – any of valid request parameters for CouchDB.
  Returns: | A dictionary containing the vulns matching the query.

`persistence.server.server.` `get_web_vulns`(workspace_name, **params)

  Get only web vulns from the server.

  Parameters: | workspace_name (str) – the workspace from which to get the vulns. **params – any of valid request parameters for CouchDB.
  Returns: | A dictionary containing the vulns matching the query.

`persistence.server.server.` `get_interfaces`(workspace_name, **params)

  Get interfaces from the server.

  Parameters: | workspace_name (str) – the workspace from which to get the interfaces. **params – any of valid request parameters for CouchDB.
  Returns: | A dictionary containing the interfaces matching the query.

`persistence.server.server.` `get_services`(workspace_name, **params)

  Get services from the server.

  Parameters: | workspace_name (str) – the workspace from which to get the services. **params – any of valid request parameters for CouchDB.
  Returns: | A dictionary containing the services matching the query.

`persistence.server.server.` `get_credentials`(workspace_name, **params)

  Get credentials from the server.

  Parameters: | workspace_name (str) – the workspace from which to get the credentials. **params – any of valid request parameters for CouchDB.
  Returns: | A dictionary containing the credentials matching the query.

`persistence.server.server.` `get_notes`(workspace_name, **params)

  Get notes from the server.

  Parameters: | workspace_name (str) – the workspace from which to get the notes. **params – any of valid request parameters for CouchDB.
  Returns: | A dictionary containing the notes matching the query.

`persistence.server.server.` `get_commands`(workspace_name, **params)

  Get commands from the server.

  Parameters: | workspace_name (str) – the workspace from which to get the commands. **params – any of valid request parameters for CouchDB.
  Returns: | A dictionary containing the commands matching the query.

`persistence.server.server.` `get_objects`(workspace_name, object_signature, **params)

  Get any type of object from the server, be it hosts, vulns, interfaces, services, credentials, commands or notes.

  Parameters: | workspace_name (str) – the workspace from which to get the commands. object_signature (str) – the type of object to get. Must equal ‘hosts’, ‘vulns’, ‘interfaces’, ‘services’, ‘credentials’, ‘notes’ or ‘commands’ **params – any of valid request parameters for CouchDB.
  Returns: | A dictionary containing the commands matching the query.
  Raises: | `WrongObjectSignature` – if the object_signature string didn’t match a faraday object.

`persistence.server.server.` `get_changes_stream`(workspace_name, since=0, heartbeat='1000', **extra_params)

`persistence.server.server.` `get_workspaces_names`()

  Returns: A dictionary with a list with the workspaces names.

`persistence.server.server.` `get_object_before_last_revision`(workspace_name, object_id)

  Get an object before its last revision. Useful to get information about recently deleted objects.

  Warning

  Error-pronce process. You should check for ‘None’ after usage, as that’s the return value if any problem arose during execution.

  Parameters: | workspace_name (str) – the workspace where the object was object_id (str) – the id of the object
  Returns: | A dictionary with the object’s information.

`persistence.server.server.` `get_object`(workspace_name, object_signature, object_id)

  Get an unique object of arbitrary type.

  Parameters: | workspace_name (str) – the workspace where the object should be found. object_signature (str) – must be either ‘hosts’, ‘vulns’, ‘interfaces’ ‘services’, ‘credentials’, ‘notes’ or ‘commands’. object_id (str) – the id of the object
  Returns: | A dictionary containing information about the object.
  Raises: | `MoreThanOneObjectFoundByID` – if for some reason the object_id is shared by two or more objects. This should never happen. If it does, contact Infobyte LCC.

`persistence.server.server.` `get_host`(workspace_name, host_id)

  Get an unique host.

  Parameters: | workspace_name (str) – the workspace where the object should be found. host_id (str) – the id of the host
  Returns: | A dictionary containing information about the host.
  Raises: | `MoreThanOneObjectFoundByID` – if for some reason the host id is shared by two or more objects. This should never happen. If it does, contact Infobyte LCC.

`persistence.server.server.` `get_vuln`(workspace_name, vuln_id)

  Get an unique vuln.

  Parameters: | workspace_name (str) – the workspace where the object should be found. vuln_id (str) – the id of the vuln
  Returns: | A dictionary containing information about the vuln.
  Raises: | `MoreThanOneObjectFoundByID` – if for some reason the vuln id is shared by two or more objects. This should never happen. If it does, contact Infobyte LCC.

`persistence.server.server.` `get_web_vuln`(workspace_name, vuln_id)

  Get an unique web vuln.

  Parameters: | workspace_name (str) – the workspace where the object should be found. vuln_id (web) – the id of the web vuln
  Returns: | A dictionary containing information about the web vuln.
  Raises: | `MoreThanOneObjectFoundByID` – if for some reason the web vuln id is shared by two or more objects. This should never happen. If it does, contact Infobyte LCC.

`persistence.server.server.` `get_interface`(workspace_name, interface_id)

  Get an unique interface.

  Parameters: | workspace_name (str) – the workspace where the object should be found. interface_id (str) – the id of the interface
  Returns: | A dictionary containing information about the interface.
  Raises: | `MoreThanOneObjectFoundByID` – if for some reason the interface id is shared by two or more objects. This should never happen. If it does, contact Infobyte LCC.

`persistence.server.server.` `get_service`(workspace_name, service_id)

  Get an unique service.

  Parameters: | workspace_name (str) – the workspace where the object should be found. service_id (str) – the id of the service
  Returns: | A dictionary containing information about the service.
  Raises: | `MoreThanOneObjectFoundByID` – if for some reason the service id is shared by two or more objects. This should never happen. If it does, contact Infobyte LCC.

`persistence.server.server.` `get_note`(workspace_name, note_id)

  Get an unique note.

  Parameters: | workspace_name (str) – the workspace where the object should be found. note_id (str) – the id of the note
  Returns: | A dictionary containing information about the note.
  Raises: | `MoreThanOneObjectFoundByID` – if for some reason the note id is shared by two or more objects. This should never happen. If it does, contact Infobyte LCC.

`persistence.server.server.` `get_credential`(workspace_name, credential_id)

  Get an unique credential.

  Parameters: | workspace_name (str) – the workspace where the object should be found. credential_id (str) – the id of the credential
  Returns: | A dictionary containing information about the credential.
  Raises: | `MoreThanOneObjectFoundByID` – if for some reason the credential id is shared by two or more objects. This should never happen. If it does, contact Infobyte LCC.

`persistence.server.server.` `get_command`(workspace_name, command_id)

  Get an unique command.

  Parameters: | workspace_name (str) – the workspace where the object should be found. command_id (str) – the id of the command
  Returns: | A dictionary containing information about the command.
  Raises: | `MoreThanOneObjectFoundByID` – if for some reason the command id is shared by two or more objects. This should never happen. If it does, contact Infobyte LCC.

`persistence.server.server.` `get_workspace`(workspace_name, **params)

  Get an unique command.

  Parameters: | command_name (str) – the command where the object should be found. command_id (str) – the id of the command
  Returns: | A dictionary containing information about the command.
  Raises: | `MoreThanOneObjectFoundByID` – if for some reason the command id is shared by two or more objects. This should never happen. If it does, contact Infobyte LCC.

`persistence.server.server.` `get_workspace_summary`(workspace_name)

  Get a collection of data about the workspace.

  Parameters: | workspace_name (str) – the workspace to get the stats from.
  Returns: | A dictionary with the workspace’s information

`persistence.server.server.` `get_workspace_numbers`(workspace_name)

  Get the number of hosts, interfaces, services and vulns in the workspace.

  Parameters: | workspace_name (str) – the name of the workspace to query
  Returns: | A tuple of 4 elements with the amounts of hosts, interfaces, services and vulns.

`persistence.server.server.` `get_hosts_number`(workspace_name, **params)

  Parameters: | workspace_name (str) – the name of the workspace to query **params – any of the Couchdb request parameters
  Returns: | The amount of hosts in the workspace as an integer.

`persistence.server.server.` `get_services_number`(workspace_name, **params)

  Parameters: | workspace_name (str) – the name of the workspace to query **params – any of the Couchdb request parameters
  Returns: | The amount of services in the workspace as an integer.

`persistence.server.server.` `get_interfaces_number`(workspace_name, **params)

  Parameters: | workspace_name (str) – the name of the workspace to query **params – any of the Couchdb request parameters
  Returns: | The amount of interfaces in the workspace as an integer.

`persistence.server.server.` `get_vulns_number`(workspace_name, **params)

  Parameters: | workspace_name (str) – the name of the workspace to query **params – any of the Couchdb request parameters
  Returns: | The amount of vulns in the workspace as an integer.

`persistence.server.server.` `get_notes_number`(workspace_name, **params)

  Parameters: | workspace_name (str) – the name of the workspace to query **params – any of the Couchdb request parameters
  Returns: | The amount of notes in the workspace as an integer.

`persistence.server.server.` `get_credentials_number`(workspace_name, **params)

  Parameters: | workspace_name (str) – the name of the workspace to query **params – any of the Couchdb request parameters
  Returns: | The amount of credentials in the workspace as an integer.

`persistence.server.server.` `get_commands_number`(workspace_name, **params)

  Parameters: | workspace_name (str) – the name of the workspace to query **params – any of the Couchdb request parameters
  Returns: | The amount of commands in the workspace as an integer.

`persistence.server.server.` `create_host`(workspace_name, id, name, os, default_gateway, description='', metadata=None, owned=False, owner='', parent=None)

  Create a host.

  Parameters: | workspace_name (str) – the name of the workspace where the host will be saved. id (str) – the id of the host. Must be unique. name (str) – the host’s name os (str) – the operative system of the host default_gateway (str) – the host’s default_gateway description (str) – a description. metadata – a collection of metadata. If you don’t know the metada. leave on None. owned (bool) – is the host owned or not? owner (str) – an owner for the host parent (Faraday Object) – the host’s parent. If you don’t know this, leave on None.
  Returns: | A dictionary with the server’s response.

`persistence.server.server.` `update_host`(workspace_name, id, name, os, default_gateway, description='', metadata=None, owned=False, owner='', parent=None)

  Updates a host.

  Parameters: | workspace_name (str) – the name of the workspace where the host will be saved. id (str) – the id of the host. Must be unique. name (str) – the host’s name os (str) – the operative system of the host default_gateway (str) – the host’s default_gateway description (str) – a description. metadata – a collection of metadata. If you don’t know the metada. leave on None, it will be created automatically. owned (bool) – is the host owned or not? owner (str) – an owner for the host parent (Faraday Object) – the host’s parent. If you don’t know this, leave on None.
  Returns: | A dictionary with the server’s response.

`persistence.server.server.` `create_interface`(workspace_name, id, name, description, mac, owned=False, owner='', hostnames=None, network_segment=None, ipv4=None, ipv6=None, metadata=None)

  Creates an interface.

  Warning

  DO NOT leave ipv4 and ipv6 values on None, as the default indicated. This is a known bug and we’re working to fix it. ipv4 and ipv6 need to be valid IP addresses, or, in case one of them is irrelevant, empty strings.

  Parameters: | workspace_name (str) – the name of the workspace where the interface will be saved. id (str) – the id of the interface. Must be unique. name (str) – the interface’s name description (str) – a description. mac (str) – owned (bool) – is the host owned or not? owner (str) – an owner for the host hostnames ([str]) – a list of hostnames network_segment (str) – the network segment ipv4 (str) – the ipv4 direction of the interface. ipv6 (str) – the ipv6 direction of the interface. metadata – a collection of metadata. If you don’t know the metada. leave on None, it will be created automatically.
  Returns: | A dictionary with the server’s response.

`persistence.server.server.` `update_interface`(workspace_name, id, name, description, mac, owned=False, owner='', hostnames=None, network_segment=None, ipv4=None, ipv6=None, metadata=None)

  Creates an interface.

  Warning

  DO NOT leave ipv4 and ipv6 values on None, as the default indicated. This is a known bug and we’re working to fix it. ipv4 and ipv6 need to be valid IP addresses, or, in case one of them is irrelevant, empty strings.

  Parameters: | workspace_name (str) – the name of the workspace where the interface will be saved. id (str) – the id of the interface. Must be unique. name (str) – the interface’s name description (str) – a description. mac (str) – owned (bool) – is the host owned or not? owner (str) – an owner for the host hostnames ([str]) – a list of hostnames network_segment (str) – the network segment ipv4 (str) – the ipv4 direction of the interface. ipv6 (str) – the ipv6 direction of the interface. metadata – a collection of metadata. If you don’t know the metada. leave on None, it will be created automatically.
  Returns: | A dictionary with the server’s response.

`persistence.server.server.` `create_service`(workspace_name, id, name, description, ports, owned=False, owner='', protocol='', status='', version='', metadata=None)

  Creates a service.

  Parameters: | workspace_name (str) – the name of the workspace where the service will be saved. id (str) – the id of the service. Must be unique. name (str) – the host’s name description (str) – a description. ports ([str]) – a list of ports for the service. owned (bool) – is the service owned or not? owner (str) – an owner for the service protocol (str) – the service’s protocol status (str) – the service’s status version (str) – the service’s version metadata – a collection of metadata. If you don’t know the metada. leave on None, it will be created automatically.
  Returns: | A dictionary with the server’s response.

`persistence.server.server.` `update_service`(workspace_name, id, name, description, ports, owned=False, owner='', protocol='', status='', version='', metadata=None)

  Creates a service.

  Parameters: | workspace_name (str) – the name of the workspace where the service will be saved. id (str) – the id of the service. Must be unique. name (str) – the service’s name description (str) – a description. ports ([str]) – a list of ports for the service. owned (bool) – is the host owned or not? owner (str) – an owner for the service protocol (str) – the service’s protocol status (str) – the service’s status version (str) – the service’s version metadata – a collection of metadata. If you don’t know the metada. leave on None, it will be created automatically.
  Returns: | A dictionary with the server’s response.

`persistence.server.server.` `create_vuln`(workspace_name, id, name, description, owned=None, owner='', confirmed=False, data='', refs=None, severity='info', resolution='', desc='', metadata=None, status=None)

  Creates a vuln.

  Parameters: | workspace_name (str) – the name of the workspace where the vuln will be saved. id (str) – the id of the vuln. Must be unique. name (str) – the vuln’s name description (str) – a description. owned (bool) – is the vuln owned or not? owner (str) – an owner for the vuln confirmed (bool) – is the vulnerability confirmed? data (str) – any aditional data about the vuln refs ([str]) – references for the vulnerability severity (str) – a string indicating the vuln’s severity. can be ‘info’, ‘low’, ‘med’, ‘high’, ‘critical’ resolution (str) – the vuln’s possible resolution desc (str) – a vuln’s description. status (str) – the service’s status metadata – a collection of metadata. If you don’t know the metada. leave on None, it will be created automatically.
  Returns: | A dictionary with the server’s response.

`persistence.server.server.` `update_vuln`(workspace_name, id, name, description, owned=None, owner='', confirmed=False, data='', refs=None, severity='info', resolution='', desc='', metadata=None, status=None)

  Updates a vuln.

  Parameters: | workspace_name (str) – the name of the workspace where the host will be saved. id (str) – the id of the host. Must be unique. name (str) – the host’s name description (str) – a description. owned (bool) – is the vuln owned or not? owner (str) – an owner for the vuln confirmed (bool) – is the vulnerability confirmed? data (str) – any aditional data about the vuln refs ([str]) – references for the vulnerability severity (str) – a string indicating the vuln’s severity. can be ‘info’, ‘low’, ‘med’, ‘high’, ‘critical’ resolution (str) – the vuln’s possible resolution desc (str) – a vuln’s description. status (str) – the service’s status metadata – a collection of metadata. If you don’t know the metada. leave on None, it will be created automatically.
  Returns: | A dictionary with the server’s response.

`persistence.server.server.` `create_vuln_web`(workspace_name, id, name, description, owned=None, owner='', confirmed=False, data='', refs=None, severity='info', resolution='', desc='', metadata=None, method=None, params='', path=None, pname=None, query=None, request=None, response=None, category='', website=None, status=None)

  Creates a vuln web.

  Parameters: | workspace_name (str) – the name of the workspace where the vuln web will be saved. id (str) – the id of the vuln web. Must be unique. name (str) – the vuln web’s name description (str) – a description. owner (str) – an owner for the host confirmed (bool) – is the vulnerability confirmed? data (str) – any aditional data about the vuln refs ([str]) – references for the vulnerability severity (str) – a string indicating the vuln’s severity. can be ‘info’, ‘low’, ‘med’, ‘high’, ‘critical’ resolution (str) – the vuln’s possible resolution desc (str) – a vuln’s description. metadata – a collection of metadata. If you don’t know the metada. leave on None, it will be created automatically. method (str) – the web vuln method params (str) – the parameters for the web vuln path (str) – the web vuln’s path query (str) – the web vuln’s query request (str) – the web vuln’s request response (str) – the web vuln’s response category (str) – a category for the web vuln’s website (str) – the website where the vuln was found status (str) – the web vulns’s status
  Returns: | A dictionary with the server’s response.

`persistence.server.server.` `update_vuln_web`(workspace_name, id, name, description, owned=None, owner='', confirmed=False, data='', refs=None, severity='info', resolution='', desc='', metadata=None, method=None, params='', path=None, pname=None, query=None, request=None, response=None, category='', website=None, status=None)

  Creates a vuln web.

  Parameters: | workspace_name (str) – the name of the workspace where the vuln web will be saved. id (str) – the id of the vuln web. Must be unique. name (str) – the vuln web’s name description (str) – a description. owner (str) – an owner for the host confirmed (bool) – is the vulnerability confirmed? data (str) – any aditional data about the vuln refs ([str]) – references for the vulnerability severity (str) – a string indicating the vuln’s severity. can be ‘info’, ‘low’, ‘med’, ‘high’, ‘critical’ resolution (str) – the vuln’s possible resolution desc (str) – a vuln’s description. metadata – a collection of metadata. If you don’t know the metada. leave on None, it will be created automatically. method (str) – the web vuln method params (str) – the parameters for the web vuln path (str) – the web vuln’s path query (str) – the web vuln’s query request (str) – the web vuln’s request response (str) – the web vuln’s response category (str) – a category for the web vuln’s website (str) – the website where the vuln was found status (str) – the web vulns’s status
  Returns: | A dictionary with the server’s response.

`persistence.server.server.` `create_note`(workspace_name, id, name, text, owned=None, owner='', description='', metadata=None)

  Creates a note.

  Parameters: | workspace_name (str) – the name of the workspace where the vuln web will be saved. id (str) – the id of the vuln web. Must be unique. name (str) – the vuln web’s name text (str) – the note’s text owned (bool) – is the note owned? owner (str) – the note’s owner description (str) – a description metadata – a collection of metadata. If you don’t know the metada. leave on None, it will be created automatically.
  Returns: | A dictionary with the server’s response.

`persistence.server.server.` `update_note`(workspace_name, id, name, text, owned=None, owner='', description='', metadata=None)

  Updates a note.

  Parameters: | workspace_name (str) – the name of the workspace where the vuln web will be saved. id (str) – the id of the vuln web. Must be unique. name (str) – the vuln web’s name text (str) – the note’s text owned (bool) – is the note owned? owner (str) – the note’s owner description (str) – a description metadata – a collection of metadata. If you don’t know the metada. leave on None, it will be created automatically.
  Returns: | A dictionary with the server’s response.

`persistence.server.server.` `create_credential`(workspace_name, id, name, username, password, owned=None, owner='', description='', metadata=None)

  Creates a credential.

  Parameters: | workspace_name (str) – the name of the workspace where the vuln web will be saved. id (str) – the id of the vuln web. Must be unique. name (str) – the vuln web’s name username (str) – password (str) – owned (bool) – is the note owned? owner (str) – the note’s owner description (str) – a description metadata – a collection of metadata. If you don’t know the metada. leave on None, it will be created automatically.
  Returns: | A dictionary with the server’s response.

`persistence.server.server.` `update_credential`(workspace_name, id, name, username, password, owned=None, owner='', description='', metadata=None)

  Updates a credential.

  Parameters: | workspace_name (str) – the name of the workspace where the vuln web will be saved. id (str) – the id of the vuln web. Must be unique. name (str) – the vuln web’s name username (str) – password (str) – owned (bool) – is the note owned? owner (str) – the note’s owner description (str) – a description metadata – a collection of metadata. If you don’t know the metada. leave on None, it will be created automatically.
  Returns: | A dictionary with the server’s response.

`persistence.server.server.` `create_command`(workspace_name, id, command, duration=None, hostname=None, ip=None, itime=None, params=None, user=None)

  Creates a command.

  Parameters: | workspace_name (str) – the name of the workspace where the vuln web will be saved. id (str) – the id of the vuln web. Must be unique. command (str) – the command to be created duration (str) – hostname (str) – the hostname where the command was executed ip (str) – the ip of the host where the command was executed itime (str) – the time it took to run params (str) – the parameters given user (str) – the user that ran the command
  Returns: | A dictionary with the server’s response.

`persistence.server.server.` `update_command`(workspace_name, id, command, duration=None, hostname=None, ip=None, itime=None, params=None, user=None)

  Updates a command.

  Parameters: | workspace_name (str) – the name of the workspace where the vuln web will be saved. id (str) – the id of the vuln web. Must be unique. command (str) – the command to be created duration (str) – hostname (str) – the hostname where the command was executed ip (str) – the ip of the host where the command was executed itime (str) – the time it took to run params (str) – the parameters given user (str) – the user that ran the command
  Returns: | A dictionary with the server’s response.

`persistence.server.server.` `create_workspace`(workspace_name, description, start_date, finish_date, customer=None)

  Create a workspace.

  Parameters: | workspace_name (str) – the workspace’s name description (str) – a description for the worksapce start_date (str) – a date to represent when work began in the workspace finish_date (str) – a date to represent when work will be finished on the workspace customer (str) – the customer for which we are creating the workspace
  Returns: | A dictionary with the server’s response.

`persistence.server.server.` `delete_host`(workspace_name, host_id)

  Delete host of id host_id from the database.

`persistence.server.server.` `delete_interface`(workspace_name, interface_id)

  Delete interface of id interface_id from the database.

`persistence.server.server.` `delete_service`(workspace_name, service_id)

  Delete service of id service_id from the database.

`persistence.server.server.` `delete_vuln`(workspace_name, vuln_id)

  Delete vuln of id vuln_id from the database.

`persistence.server.server.` `delete_note`(workspace_name, note_id)

  Delete note of id note_id from the database.

`persistence.server.server.` `delete_credential`(workspace_name, credential_id)

  Delete credential of id credential_id from the database.

`persistence.server.server.` `delete_command`(workspace_name, command_id)

  Delete command of id command_id from the database.

`persistence.server.server.` `delete_workspace`(workspace_name)

  Delete the couch database of id workspace_name

`persistence.server.server.` `is_server_up`()

  Return True if we can stablish a connection with the server, False otherwise.

`persistence.server.server.` `test_server_url`(url_to_test)

  Return True if the url_to_test is indeed a valid Faraday Server URL. False otherwise.