AtomShields’s documentation¶

Getting started¶

What is AtomShields?¶

Security testing framework for repositories and source code.

This system has different modules that detect different vulnerabilities or files that may expose a risk, and the results obtained can be obtained or sent thanks to the reporting modules.

For developers: There is also the possibility to develop your own vulnerability detection (called checkers) or reporting modules. This tool offers certain facilities for those who want to implement their own modules, publish them and integrate them into the official ElevenPaths tool.

Installation¶

pip install atomshields

Basic usage¶

import atomshields

atoms = atomshields.AtomShieldsScanner('./MyRepo/')
atoms.project = "MyRepoName"

issues = atoms.executeCheckers()

Run tests¶

# If you are in AtomShields directory
pip install -r requirements-dev.txt
py.test tests/

Generate docs¶

# If you are in AtomShields directory
pip install -r requirements-dev.txt
cd docs
make html

Checkers¶

DS_STORE¶

DS_STORE is a Mac OS X file containing information about the system that created it. These files are rarely filtered in. gitignore, providing information about the system of the author of the repository.

atomshields.checkers.dsstore.DSStoreChecker()

RetireJS¶

The goal of Retire.js is to help you detect use of version of JavaScript libraries with known vulnerabilities. This checker finds js files with vulnerabilities. Also, the checker finds and download JS files linked via URL.

atomshields.checkers.retirejs.RetireJSChecker()

Target-blank¶

This checker helps you to detect the target blank vulnerability in your code files. For more details about the vulnerability please see this link.

atomshields.checkers.targetblank.TargetBlankChecker()

Reports¶

Echo¶

This reports prints on screen a summary of all issues found. The fields printed are Name, Severity and File affected.

atomshields.reports.echo.EchoReport(*args, …) This module shows all the information about the vulnerabilities per screen (echo).

Http Request¶

Sends hte full information of issues via HTTP. The endpoint must be setted into the config file in the directory .atomshields into your home path.

atomshields.reports.http.HttpReport(*args, …) This module sends all information about vulnerabilities to an endpoint via an http request.

atomshields¶

atomshields package¶

Subpackages¶

atomshields.checkers package¶

Submodules¶

atomshields.checkers.base module¶

class atomshields.checkers.base.GenericChecker[source]¶

Bases: object

dao¶

Getter for ‘dao’ property

Returns:	Instance of DAO class
Return type:	atomshield.helpers.DAO

path¶

Getter for ‘path’ property

Returns:	Absolute path to scan
Return type:	str

project¶

Getter for ‘project’ property

Returns:	Project’s name
Return type:	str

issues¶

Getter for ‘issues’ property

Returns:	List of instances of Issue class
Return type:	list<atomshields.helpers.Issue>

config¶

Getter for ‘config’ property

Returns:	Dictionary which contains the current values for this report config
Return type:	dict

test()[source]¶

Check if the checker is OK to run.

This method should to run every test (requirements) in order to ensure the excution will not have errors.

Returns:	True if the checker has all the requirements installed. False else
Return type:	bool

run()[source]¶: Abstract method. This method will be executed for subclass which not implemented his own method

saveIssue(issue)[source]¶

Stores an issue in ‘issues’ property

Parameters:	issue (atomshields.helpers.Issue) – Issue instance

classmethod parseConfig(value)[source]¶

Parse the config values

Parameters:	value (dict) – Dictionary which contains the checker config
Returns:	The checker config with parsed values
Return type:	dict

static isInstalled()[source]¶

Check if a software is installed into machine.

Parameters:	value (str) – Software’s name
Returns:	True if the software is installed. False else
Return type:	bool

atomshields.checkers.base.checker(func)[source]¶: Decorator for method run. This method will be execute before the execution from the method with this decorator.

atomshields.checkers.dsstore module¶

class atomshields.checkers.dsstore.DSStoreChecker[source]¶

Bases: atomshields.checkers.base.GenericChecker

NAME = 'dsstore'¶

DESCRIPTION = 'Busca y elimina los ficheros .DS_Store'¶

CONFIG = {'enabled': True, 'exclude_paths': [], 'remove': True}¶

run(*args, **kwargs)¶

atomshields.checkers.retirejs module¶

class atomshields.checkers.retirejs.RetireJSChecker[source]¶

Bases: atomshields.checkers.base.GenericChecker

NAME = 'retirejs'¶

DESCRIPTION = 'Detecta ficheros JavaScript vulnerables'¶

CONFIG = {'enabled': True, 'exclude_paths': ['test/']}¶

run(*args, **kwargs)¶

scan(path, options='', tempfile=False)[source]¶

download(url, path)[source]¶

getLastVersion(component)[source]¶

getJSLinks(filepath)[source]¶

static install()[source]¶: Install all the dependences

test()[source]¶

Check the dependences.

Returns:	True if all dependences are installed. False else.
Return type:	bool

atomshields.checkers.targetblank module¶

class atomshields.checkers.targetblank.TargetBlankChecker[source]¶

Bases: atomshields.checkers.base.GenericChecker

NAME = 'targetblank'¶

DESCRIPTION = "Detecta vulnerabilidades 'Target Blank' en ficheros HTML"¶

CONFIG = {'enabled': True, 'exclude_paths': ['/test/', '/docs/']}¶

REGEX = u'(<a (?=.*href=([\'\\"])(https?:)?\\/\\/.*?\\2)(?!.*rel=([\'\\"])(.*\\bnoopener\\b.*\\bnoreferrer\\b.*|.*\\bnoreferrer\\b.*\\bnoopener\\b.*)\\4)[^>]*target=([\'\\"]?)_blank\\6[^>]*)(>)([^<]*)(<\\/a>)?'¶

run(*args, **kwargs)¶

Module contents¶

atomshields.models package¶

Submodules¶

atomshields.models.issue module¶

class atomshields.models.issue.Issue(name=None, file=None, details=None, severity=None, potential=None, checker_name=None)[source]¶

Bases: object

Type of object returned by all checkers.

Este es el modelo genérico que será generado por cada vulnerabilidad encontrada por los checkers y tratada por los modulos de reporte.

SEVERITY_INFO¶: str – Name of the incidences of informatic value

SEVERITY_LOW¶: str – Name of incidents with low criticality

SEVERITY_MEDIUM¶: str – Name of incidents with medium criticality

SEVERITY_HIGH¶: str – Name of requests with high criticality

SEVERITY_CRITICAL¶: str – Name of the requests with very high criticality

_name¶: str – Name of the request

_file¶: str – File affected by the incident

_details¶: str – Other details about the incident

_severity¶: str – Criticism of the incidence

_potential¶: bool

_checker_name¶: str – Name of the module that detected the request

SEVERITY_INFO = 'Info'

SEVERITY_LOW = 'Low'

SEVERITY_MEDIUM = 'Medium'

SEVERITY_HIGH = 'High'

SEVERITY_CRITICAL = 'Critical'

name¶

Getter for ‘name’ property

Returns:	Issue’s name
Return type:	string

file¶

Getter for ‘file’ property

Returns:	Issue’s file
Return type:	string

severity¶

Getter for ‘severity’ property

Returns:	Issue’s severity
Return type:	string

potential¶

Getter for ‘potential’ property

Returns:	potential is required?
Return type:	bool

details¶

Getter for ‘details’ property

Returns:	Issue’s details
Return type:	string

checker¶

Getter for ‘checker’ property

Returns:	Issue’s checker
Return type:	string

Module contents¶

class atomshields.models.Issue(name=None, file=None, details=None, severity=None, potential=None, checker_name=None)[source]¶

Bases: object

Type of object returned by all checkers.

Este es el modelo genérico que será generado por cada vulnerabilidad encontrada por los checkers y tratada por los modulos de reporte.

SEVERITY_INFO¶: str – Name of the incidences of informatic value

SEVERITY_LOW¶: str – Name of incidents with low criticality

SEVERITY_MEDIUM¶: str – Name of incidents with medium criticality

SEVERITY_HIGH¶: str – Name of requests with high criticality

SEVERITY_CRITICAL¶: str – Name of the requests with very high criticality

_name¶: str – Name of the request

_file¶: str – File affected by the incident

_details¶: str – Other details about the incident

_severity¶: str – Criticism of the incidence

_potential¶: bool

_checker_name¶: str – Name of the module that detected the request

SEVERITY_INFO = 'Info'

SEVERITY_LOW = 'Low'

SEVERITY_MEDIUM = 'Medium'

SEVERITY_HIGH = 'High'

SEVERITY_CRITICAL = 'Critical'

name¶

Getter for ‘name’ property

Returns:	Issue’s name
Return type:	string

file¶

Getter for ‘file’ property

Returns:	Issue’s file
Return type:	string

severity¶

Getter for ‘severity’ property

Returns:	Issue’s severity
Return type:	string

potential¶

Getter for ‘potential’ property

Returns:	potential is required?
Return type:	bool

details¶

Getter for ‘details’ property

Returns:	Issue’s details
Return type:	string

checker¶

Getter for ‘checker’ property

Returns:	Issue’s checker
Return type:	string

atomshields.reports package¶

Submodules¶

atomshields.reports.base module¶

class atomshields.reports.base.GenericReport(issues=None)[source]¶

Bases: object

Class inherited by all reporting modules.

issues¶

Getter for ‘issues’ property

Returns:	List of Issue instances
Return type:	list

config¶

Getter for ‘config’ property

Returns:	Dictionary which contains the current values for this report config
Return type:	dict

project¶

Getter for ‘project’ property

Returns:	Project’s name
Return type:	str

atomshields.reports.base.report(func)[source]¶: Decorator for method run. This method will be execute before the execution from the method with this decorator.

atomshields.reports.echo module¶

class atomshields.reports.echo.EchoReport(*args, **kwargs)[source]¶

Bases: atomshields.reports.base.GenericReport

This module shows all the information about the vulnerabilities per screen (echo).

NAME¶: str – Name of the module.

DESCRIPTION¶: str – Description of the functionality of the module.

CONFIG¶: dict – Default values of the module configuration..

NAME = 'echo'

DESCRIPTION = 'Muestra las vulnerabilidades por pantalla'

CONFIG = {'enabled': True}

run(*args, **kwargs)¶

atomshields.reports.http module¶

class atomshields.reports.http.HttpReport(*args, **kwargs)[source]¶

Bases: atomshields.reports.base.GenericReport

This module sends all information about vulnerabilities to an endpoint via an http request.

Attributes: NAME (str): Name of the module. DESCRIPTION (str): Description of the functionality of the module. CONFIG (dict): Default values of the module configuration.

NAME = 'http'¶

DESCRIPTION = 'Envia los datos de las vulnerabilidades a un endpoint HTTP'¶

CONFIG = {'enabled': False, 'method': 'post', 'proxy': 'http://127.0.0.1:8080', 'url': '<your_endpoint>', 'use_proxy': False}¶

run(*args, **kwargs)¶

Module contents¶

Submodules¶

atomshields.helpers module¶

class atomshields.helpers.CommandHelper(command=None)[source]¶

Bases: object

Class used to execute commands in shell, an d get the output and the errors.

OS_UBUNTU = 'Ubuntu'¶

OS_DEBIAN = 'Debian'¶

OS_CENTOS = 'CentOS'¶

OS_REDHAT = 'Redhat'¶

OS_KALI = 'Kali'¶

OS_LINUX = 'Linux'¶

OS_MAC = 'Darwin'¶

OS_WINDOWS = 'Windows'¶

command¶

Getter for ‘command’ property

Returns:	Command to execute
Return type:	str

output¶

Getter for ‘output’ property

Returns:	Stdout content
Return type:	str

errors¶

Getter for ‘errors’ property

Returns:	Stderr content
Return type:	str

getOSName()[source]¶

Get the OS name. If OS is linux, returns the Linux distribution name

Returns:	OS name
Return type:	str

install(software, uninstall=False)[source]¶

execute(shell=True)[source]¶

Executes the command setted into class

Parameters:	shell (boolean) – Set True if command is a shell command. Default: True

atomshields.scanner module¶

class atomshields.scanner.AtomShieldsScanner(path, verbose=False)[source]¶

Bases: object

Class in charge of orchestrating the execution of the cherckers and the results.

HOME = '/usr/local/share/atomshields'¶

HOME_2 = '/home/docs/.atomshields'¶

CHECKERS_DIR = '/home/docs/.atomshields/checkers'¶

REPORTS_DIR = '/home/docs/.atomshields/reports'¶

CONFIG_PATH = '/home/docs/.atomshields/config'¶

debug(message, color=None, attrs=None)[source]¶

path¶

Getter for ‘path’ property

Returns:	Absolute path to target directory
Return type:	string

project¶

Getter for ‘project’ property

Returns:	Projects’s name
Return type:	string

configFile¶

Getter for ‘configFile’ property

Returns:	Path to config file
Return type:	str

config¶

Getter for ‘config’ property

Returns:	Path to config file
Return type:	str

issues¶

Getter for ‘issues’ property

Returns:	List of Issue instances
Return type:	list

static setup()[source]¶: Creates required directories and copy checkers and reports.

static installPlugin(destination)[source]¶

static installChecker()[source]¶

static installReport()[source]¶

static uninstallPlugin(name=None, classArgs=None)[source]¶

static uninstallChecker()[source]¶

static uninstallReport()[source]¶

static generateConfig()[source]¶

showScanProperties()[source]¶

checkProperties()[source]¶

getConfig(section=None)[source]¶

Returns a dictionary which contains the current config. If a section is setted, only will returns the section config

Parameters:	section (str) – (Optional) Section name.
Returns:	Representation of current config
Return type:	dict

loadConfig()[source]¶

executeCheckers()[source]¶

executeReports()[source]¶

saveIssue(issue)[source]¶

showSummary()[source]¶

run()[source]¶: Run a scan in the path setted.

Module contents¶

class atomshields.AtomShieldsScanner(path, verbose=False)[source]¶

Bases: object

Class in charge of orchestrating the execution of the cherckers and the results.

HOME = '/usr/local/share/atomshields'¶

HOME_2 = '/home/docs/.atomshields'¶

CHECKERS_DIR = '/home/docs/.atomshields/checkers'¶

REPORTS_DIR = '/home/docs/.atomshields/reports'¶

CONFIG_PATH = '/home/docs/.atomshields/config'¶

debug(message, color=None, attrs=None)[source]¶

path¶

Getter for ‘path’ property

Returns:	Absolute path to target directory
Return type:	string

project¶

Getter for ‘project’ property

Returns:	Projects’s name
Return type:	string

configFile¶

Getter for ‘configFile’ property

Returns:	Path to config file
Return type:	str

config¶

Getter for ‘config’ property

Returns:	Path to config file
Return type:	str

issues¶

Getter for ‘issues’ property

Returns:	List of Issue instances
Return type:	list

static setup()[source]¶: Creates required directories and copy checkers and reports.

static installPlugin(destination)[source]¶

static installChecker()[source]¶

static installReport()[source]¶

static uninstallPlugin(name=None, classArgs=None)[source]¶

static uninstallChecker()[source]¶

static uninstallReport()[source]¶

static generateConfig()[source]¶

showScanProperties()[source]¶

checkProperties()[source]¶

getConfig(section=None)[source]¶

Returns a dictionary which contains the current config. If a section is setted, only will returns the section config

Parameters:	section (str) – (Optional) Section name.
Returns:	Representation of current config
Return type:	dict

loadConfig()[source]¶

executeCheckers()[source]¶

executeReports()[source]¶

saveIssue(issue)[source]¶

showSummary()[source]¶

run()[source]¶: Run a scan in the path setted.

class atomshields.CommandHelper(command=None)[source]¶

Bases: object

Class used to execute commands in shell, an d get the output and the errors.

OS_UBUNTU = 'Ubuntu'¶

OS_DEBIAN = 'Debian'¶

OS_CENTOS = 'CentOS'¶

OS_REDHAT = 'Redhat'¶

OS_KALI = 'Kali'¶

OS_LINUX = 'Linux'¶

OS_MAC = 'Darwin'¶

OS_WINDOWS = 'Windows'¶

command¶

Getter for ‘command’ property

Returns:	Command to execute
Return type:	str

output¶

Getter for ‘output’ property

Returns:	Stdout content
Return type:	str

errors¶

Getter for ‘errors’ property

Returns:	Stderr content
Return type:	str

getOSName()[source]¶

Get the OS name. If OS is linux, returns the Linux distribution name

Returns:	OS name
Return type:	str

install(software, uninstall=False)[source]¶

execute(shell=True)[source]¶

Executes the command setted into class

Parameters:	shell (boolean) – Set True if command is a shell command. Default: True

What is AtomShields?¶

Security testing framework for repositories and source code.

This system has different modules that detect different vulnerabilities or files that may expose a risk, and the results obtained can be obtained or sent thanks to the reporting modules.

For developers: There is also the possibility to develop your own vulnerability detection (called checkers) or reporting modules. This tool offers certain facilities for those who want to implement their own modules, publish them and integrate them into the official ElevenPaths tool.

Installation¶

pip install atomshields

Basic usage¶

import atomshields

atoms = atomshields.AtomShieldsScanner('./MyRepo/')
atoms.project = "MyRepoName"

issues = atoms.executeCheckers()

AtomShields’s documentation¶

Getting started¶

What is AtomShields?¶

Installation¶

Basic usage¶

Run tests¶

Generate docs¶

Checkers¶

DS_STORE¶

RetireJS¶

Target-blank¶

Reports¶

Echo¶

Http Request¶

atomshields¶

atomshields package¶

Subpackages¶

atomshields.checkers package¶

Submodules¶

atomshields.checkers.base module¶

atomshields.checkers.dsstore module¶

atomshields.checkers.retirejs module¶

atomshields.checkers.targetblank module¶

Module contents¶

atomshields.models package¶

Submodules¶

atomshields.models.issue module¶

Module contents¶

atomshields.reports package¶

Submodules¶

atomshields.reports.base module¶

atomshields.reports.echo module¶

atomshields.reports.http module¶

Module contents¶

Submodules¶

atomshields.helpers module¶

atomshields.scanner module¶

Module contents¶

What is AtomShields?¶

Installation¶

Basic usage¶

Indices and tables¶