Package: edgescan
An API client for EdgescanOverviewEdgescanEdgescanis a vulnerability management solution that allows you to identify both network and application layer vulnerabilities across a wide variety of systems.Data modelEdgescan's data model includes:Assets: define whichhoststo scan forvulnerabilities;Hosts: represent individual computer systems (physical or virtual); andVulnerabilities: represent known attack vectors that may be exploited by an adversary;Licenses: are mapped toassetsand store information such as which license is in use and when it expires.API clientThis API client is written in Python and includes a command line interface that you can use to list, count, and retrieve objects.FeaturesYou can use this package to:List, count, and retrieve assets, hosts, licenses, and vulnerabilities; andExport data from Edgescan in JSONL formatDisclaimersThis package is not maintained by, or supported by Edgescan.WarningsThe latest version of all hosts, licenses, and vulnerabilities will be written to the system's temporary directory by default1.1. You can disable this behaviour by settingEDGESCAN_ENABLE_CACHE=falseInstallationTo install usingpip:python3-mpipinstalledgescanTo install from source (requirespoetry):gitclonehttps://github.com/whitfieldsdad/edgescan-api-client.gitcdedgescan-api-client
makeinstallEnvironment variablesNameDescriptionDefaultRequiredEDGESCAN_HOSTAddress of Edgescan APIlive.edgescan.comfalseEDGESCAN_API_KEYEdgescan API keyn/atrueEDGESCAN_ENABLE_CACHEEnable/disable caching to temporary directory.n/afalseCONTAINER_IMAGEName of the container imageedgescan-api-clientfalseCONTAINER_REGISTRYContainer registry to which the container image will be releasedlocalhost:5000falseTestingTo run the unit tests and integration tests:maketestCode coverageAfter running the tests, you can generate code coverage reports by running:makecoverageThis will generate the following reports:HTML-formatted code coverage report:coverage/html/index.htmlJSON-formatted code coverage report:coverage/json/coverage.jsonReading the HTML-formatted code coverage reportTo read the HTML-formatted code coverage report in your default web browser, execute one of the following commands (depending on your operating system):On Windows:startcoverage/html/index.htmlOn macOS:opencoverage/html/index.htmlOn Linux:xdg-opencoverage/html/index.htmlReading the JSON-formatted code coverage reportTo read the JSON-formatted code coverage report through the command line, execute the following command:On Windows:typecoverage/json/coverage.json|jqOn Linux or macOS:catcoverage/json/coverage.json|jqDockerThis repository includes aDockerfilethat you can use to build a container image providing the API client.The image is based onpython:3.9-slim-busterand invokes the command line interface for the Edgescan API client when the container is run.Related Makefile targets:container: alias forbuild-containerbuild-container: builds the container imageexport-container: exports the container image to a file namededgescan-api-client.tar.gzin the current directoryimport-container: imports the container image from a file namededgescan-api-client.tar.gzin the current directoryrelease-container: releases the container to the configured container registryRelated environment variables:CONTAINER_IMAGE: the name of the container image (default:edgescan-api-client)CONTAINER_REGISTRY: the container registry to which the container image will be released (default:localhost:5000)Building the container imageTo build the container image:makebuild-containerExporting the container image to a fileTo export the container image to a file namededgescan-api-client.tar.gzin the current directory:makeexport-containerImporting the container image from a fileTo import the container image from a file namededgescan-api-client.tar.gzin the current directory:makeimport-containerRunning the containerTo run the container:dockerrun--rm-itedgescan-api-clientBuilding the containerTo build the container:makebuild-containerExporting the container to a fileTo export the container to a file namededgescan-api-client.tar.gz:$makeexport-container
$du-shedgescan-api-client.tar.gz
176Medgescan-api-client.tar.gzGeneral usageThere are two different ways to interact with this module:Via the command line; orVia PythonCommand line interfaceUsingpoetry:$poetryrunedgescan
Usage:edgescan[OPTIONS]COMMAND[ARGS]...

Options:--edgescan-hostTEXT--edgescan-api-keyTEXT--helpShowthismessageandexit.

Commands:assetsQueryorcountassets.hostsQueryorcounthosts.licensesQueryorcountlicenses.vulnerabilitiesQueryorcountvulnerabilities.Search for assetsYou can search for assets by:Asset ID;Name;Tag;Create time; and/orUpdate time$poetryrunedgescanassetsget-assets--help
Usage:edgescanassetsget-assets[OPTIONS]Searchforassets.

Options:--asset-idsTEXT--namesTEXT--tagsTEXT--min-create-timeTEXT--max-create-timeTEXT--min-update-timeTEXT--max-update-timeTEXT--limitINTEGER--helpShowthismessageandexit.Search for hostsYou can search for hosts by:Asset ID;Host ID;Location (i.e. by IP address or hostname);Status (i.e. whether they're "dead" or "alive");Create time; and/orUpdate time.$poetryrunedgescanhostsget-hosts--help
Usage:edgescanhostsget-hosts[OPTIONS]Searchforhosts.

Options:--asset-idsTEXT--host-idsTEXT--locationsTEXT--alive/--dead--min-create-timeTEXT--max-create-timeTEXT--min-update-timeTEXT--max-update-timeTEXT--limitINTEGER--helpShowthismessageandexit.Count active vs. inactive hostsYou can count active hosts like this:$poetryrunedgescanhostscount-hosts--alive123And inactive hosts like this:$poetryrunedgescanhostscount-hosts--dead456Count hosts by OS typeYou can count hosts by OS type like this:$poetryrunedgescanhostscount-hosts--group-byos_type|jqSearch for vulnerabilitiesYou can search for vulnerabilities by:Vulnerability ID;CVE ID;Asset ID;Host ID;Location (i.e. by IP address or hostname);Status (i.e. whether the host is "dead" or "alive");Layer (i.e. "app" layer or "network" layer);Create time;Update time$poetryrunedgescanvulnerabilitiesget-vulnerabilities--help
Usage:edgescanvulnerabilitiesget-vulnerabilities[OPTIONS]Listvulnerabilities.

Options:--vulnerability-idsTEXT--cve-idsTEXT--asset-idsTEXT--host-idsTEXT--locationsTEXT--alive/--dead--include-application-layer-vulnerabilities/--exclude-application-layer-vulnerabilities--include-network-layer-vulnerabilities/--exclude-network-layer-vulnerabilities--min-create-timeTEXT--max-create-timeTEXT--min-update-timeTEXT--max-update-timeTEXT--limitINTEGER--helpShowthismessageandexit.Count vulnerabilities by nameYou can count vulnerabilities by name like this:poetryrunedgescanvulnerabilitiescount-vulnerabilities--group-byname|jqCount vulnerabilities by locationYou can count vulnerabilities by location (i.e. by IP address or hostname) like this:poetryrunedgescanvulnerabilitiescount-vulnerabilities--group-bylocation|jqCount vulnerabilities by layer (i.e. "application" layer or "network" layer)You can count vulnerabilities by layer (i.e. "application" layer or "network" layer) like this:poetryrunedgescanvulnerabilitiescount-vulnerabilities--group-bylayer|jqSearch for licensesYou can search for licenses by:License ID;License name; and/orWhether the license is expired.$poetryrunedgescanlicensesget-licenses--help
Usage:edgescanlicensesget-licenses[OPTIONS]Listlicenses.

Options:--license-idsTEXT--license-namesTEXT--expired/--not-expired--limitINTEGER--helpShowthismessageandexit.PythonSearch for assetsTo look up all assets and list their names:fromedgescanimportClientapi=Client()assets=api.iter_assets()names={asset['name']forassetinassets}print(', '.join(sorted(names)))Search for hostsTo look up all active hosts and list their locations (i.e. IP addresses and hostnames):fromedgescanimportClientapi=Client()locations=set()forhostinapi.iter_hosts(alive=True):locations|={host['location']}|set(host['hostnames'])print(', '.join(sorted(locations)))To look up all active hosts and their OS versions:fromedgescanimportClientapi=Client()os_versions={host['os_name']forhostinapi.iter_hosts(alive=True)ifhost['os_name']}print(', '.join(sorted(os_versions)))To count active hosts by OS type and OS version:fromedgescanimportClientfromcollectionsimportOrderedDictimportedgescan.platformsimportcollectionsimportjsonapi=Client()tally=collections.defaultdict(lambda:collections.defaultdict(int))forhostinapi.iter_hosts(alive=True):os_version=host['os_name']ifos_version:os_type=edgescan.platforms.parse_os_type(os_version)tally[os_type][os_version]+=1#: Sort by rate of occurrence.tally=OrderedDict(sorted(tally.items(),key=lambdae:e[1],reverse=True))print(json.dumps(tally,indent=4))Search for licensesTo search for licenses and list their names:fromedgescanimportClientapi=Client()names={row['name']forrowinapi.iter_licenses()}print(', '.join(sorted(names)))Search for vulnerabilitiesTo count vulnerabilities on active hosts:fromedgescanimportClientapi=Client()total=api.count_vulnerabilities(host_is_alive=True)print(total)To count vulnerabilities on active hosts by CVE ID:fromedgescanimportClientfromcollectionsimportOrderedDictimportcollectionsimportjsonapi=Client()tally=collections.defaultdict(int)forvulnerabilityinapi.iter_vulnerabilities(host_is_alive=True):forcve_idinvulnerability['cves']:tally[cve_id]+=1#: Sort by rate of occurrence.tally=OrderedDict(sorted(tally.items(),key=lambdae:e[1],reverse=True))print(json.dumps(tally,indent=4))Data exportYou can export all assets, licenses, hosts, and vulnerabilities as follows:./scripts/export-all-jsonl.shYou can provide a custom output directory using the EDGESCAN_OUTPUT_DIRECTORY environment variable:EDGESCAN_OUTPUT_DIRECTORY=/tmp/edgescan/data./scripts/export-all-jsonl.sh&&du-sh$EDGESCAN_OUTPUT_DIRECTORY/*