mage.api_resources.assessment_run module¶

class mage.api_resources.assessment_run.AssessmentRun¶

Bases: mage.api_resources.abstract.listable_api_resource.ListableAPIResource, mage.api_resources.abstract.mutable_api_resource.MutableAPIResource, mage.api_resources.abstract.filterable_api_resource.FilterableAPIResource

The execution of an assessment at a specific point in time.

asm_graph¶

A signed URL to the D3 network graph for ATTACK_SURFACE_MONITORING assessments

Type: mage.schema.AWSJSON

assessment_id¶

ID of the associated assessment

Type: str

created_at¶

When the assessment run was created (e.g., ‘2020-01-02T03:04:56.789Z’)

Type: str

fail_reason¶

The reason for assessment run failure

Type: str

id¶

Unique assessment run ID

Type: str

last_run_id¶

ID of the assessment run that ran previous to this one for this assessment

Type: str

metadata¶

Statistics for the assessment run

Type: mage.schema.AssessmentRunMetadata

phishing_results¶

Type: list of mage.schema.PhishingResult

recon¶

The recon results for this assessment run

Type: mage.schema.AWSJSON

score¶

The assessment run’s score

Type: float

stager¶

The command to run on an internal computer to begin an internal assessment

Type: str

state¶

Current state of the assessment run

Type: mage.schema.AssessmentState

updated_at¶

When the assessment run was last updated (e.g., ‘2020-01-02T03:04:56.789Z’)

Type: str

property assessment¶

The associated assessment.

Returns: Assessment

property connections¶

A list of relationships between assets.

Returns: ListObject of AssetConnection

property credentials¶

The list of credentials associated with this assessment run.

Returns: ListObject of Credential

property discovered_assets¶

Assets discovered during the assessment run.

Returns: ListObject of AssessmentRunAssetConnection

classmethod email_report(emails=None, assessment_run_id=None)¶

Emails the assessment run’s report to the provided email addresses.

Parameters

emails (str or list of str, optional) – List of email addresses to send the report to. Defaults to the associated assessment’s report_recipients
assessment_run_id (str, optional) – ID of the assessment run to generate the report for

Examples

Class Method:

>>> import mage
>>> mage.connect()
>>> mage.AssessmentRun.email_report('someone@example.com', '12345')
>>> mage.AssessmentRun.email_report(['thing1@example.com', 'thing2@example.com'], '12345')

Instance Method:

>>> import mage
>>> mage.connect()
>>> ar = mage.AssessmentRun.last()[0]
>>> ar.email_report('someone@example.com')
>>> ar.email_report(['thing1@example.com', 'thing2@example.com'])

property findings¶

Findings associated with this assessment run.

Returns: ListObject of Finding

property findings_filter¶

Findings associated with this assessment run.

Returns: Filter

Example

>>> import mage
>>> mage.connect()
>>> ar = mage.AssessmentRun.last()[0]
>>> list(ar.findings_filter.last(20))

classmethod get_report_url(assessment_run_id=None)¶

Gets the download URL for the assessment run’s report.

Parameters: assessment_run_id (str, optional) – ID of the assessment run to get the URL for
Returns: URL to the assessment run’s report
Return type: str

Warning

This call may time out if it takes too long to generate the report. Consider using email_report instead.

Examples

Class Method:

>>> import mage
>>> mage.connect()
>>> mage.AssessmentRun.get_report_url('11111111-1111-1111-1111-111111111111')

Instance Method:

>>> import mage
>>> mage.connect()
>>> ar = mage.AssessmentRun.last()[0]
>>> ar.get_report_url()

classmethod get_zip_url(assessment_run_id=None)¶: Gets the download URL for a zip archive of the run’s results.

property leads¶

Leads associated with this assessment run.

Returns: ListObject of Lead

property leads_filter¶

Leads associated with this assessment run.

Returns: Filter

Example

>>> import mage
>>> mage.connect()
>>> ar = mage.AssessmentRun.last()[0]
>>> list(ar.leads_filter.select('title').match(title='http').auto_paging_iter())

property report_url¶

The assessment report URL.

Returns: str

classmethod stop(assessment_run_id=None)¶

Stops the assessment if running.

Parameters: assessment_run_id (str, optional) – ID of the assessment run to stop
Returns: True on success, False on error
Return type: bool

Examples

Class Method:

>>> import mage
>>> mage.connect()
>>> a = mage.Assessment.eq(name="test")[0]
>>> run_id = a.start()
>>> mage.AssessmentRun.stop(run_id)

Instance Method:

>>> import mage
>>> mage.connect()
>>> mage.AssessmentRun.last()[0].stop()

property ttps¶

TTPs associated with this assessment run.

Returns: ListObject of TTP

property ttps_filter¶

TTPs associated with this assessment run.

Returns: Filter

Example

>>> import mage
>>> mage.connect()
>>> ar = mage.AssessmentRun.last()[0]
>>> list(ar.ttps_filter.last(20))