mage.api_resources.assessment module¶

class mage.api_resources.assessment.Assessment¶

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

created_at¶

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

Type: str

externally_assess_cloud_assets¶

Type: bool

id¶

Unique assessment ID

Type: str

name¶

The assessment’s name (e.g., ‘My Assessment’)

Type: str

phishing_configuration¶

Type: mage.schema.PhishingConfiguration

report_recipients¶

List of email addresses to send run reports to

Type: list of mage.schema.AWSEmail

schedule¶

When and how often this assessment will automatically be run

Type: mage.schema.Schedule

type¶

The assessment’s type

Type: mage.schema.AssessmentType

updated_at¶

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

Type: str

property asset_groups¶

The list of asset groups associated with this assessment.

Returns: ListObject of mage.api_resources.asset_group.AssetGroup objects
Return type: mage.api_resources.abstract.listable_api_resource.ListObject

property asset_groups_filter¶

The list of asset groups associated with this assessment.

Returns: Filter Object
Return type: mage.api_resources.abstract.filterable_api_resource.Filter

Example

>>> import mage
>>> mage.connect()
>>> assessment = mage.Assessment.eq(name='My Cloud Test')[0]
>>> for group in assessment.asset_groups_filter.search().auto_paging_iter():
>>>    print(group.name)

property assets¶

The list of assets associated with this assessment.

Returns: ListObject of mage.api_resources.asset.Asset objects
Return type: mage.api_resources.abstract.listable_api_resource.ListObject

Example

>>> import mage
>>> mage.connect()
>>> assessment = mage.Assessment.eq(name='My Cloud Test')[0]
>>> for asset in assessment.assets.auto_paging_iter():
>>>    print(asset.asset.asset_identifier())

property cloud_credentials¶

The list of cloud credentials associated with this assessment.

Returns: ListObject of mage.api_resources.cloud_credential.CloudCredential objects
Return type: mage.api_resources.abstract.listable_api_resource.ListObject

property cloud_credentials_filter¶

The list of cloud credentials associated with this assessment.

Returns: Filter Object
Return type: mage.api_resources.abstract.filterable_api_resource.Filter

Example

>>> import mage
>>> mage.connect()
>>> assessment = mage.Assessment.eq(name='My Cloud Test')[0]
>>> assessment.cloud_credentials_filter

connect(item=None, asset_id=None, asset_group_id=None)¶

Connect an assessment to an asset or asset group

Parameters

item (object, optional) – Assessment or AssessmentRun or AssetGroup to connect the asset to
asset_id (str, optional) – ID of the asset to connect the assessment to
asset_group_id (str, optional) – ID of the asset group to connect the asset to

Returns

assessment_asset_connection.AssessmentAssetConnection or assessment_asset_group_connection.AssessmentAssetGroupConnection

Example

>>> import mage
>>> mage.connect()
>>> asset = mage.Asset.eq(asset_identifier='www.example.com')[0]
>>> asset.connect(mage.Assessment.last()[0])
>>> ar = mage.AssessmentRun.last()[0]
>>> asset.connect(assessment_run_id=ar.id)

classmethod create(assessment_type, **kwargs)¶

Creates a new assessment of the given type.

Parameters

assessment_type (mage.schema.AssessmentType) – The type of assessment to create.
**kwargs – Additional arguments to initialize the assessment with.

Returns

Created assessment on success or None on failure.

Return type

mage.api_resources.assessment.Assessment

Example

>>> import mage
>>> mage.connect()
>>> mage.Assessment.create('EXTERNAL')
>>> mage.Assessment.create('CLOUD', name='My Cloud Test')

classmethod create_schedule(frequency, time_expression, assessment_id=None)¶

Schedules the assessment to repeatedly run.

Parameters

frequency (mage.schema.ScheduleFrequency) – How often to run the assessment
time_expression (dict) – When to run the assessment at the given frequency
assessment_id (str, optional) – Assessment ID to schedule

Returns

True on success, False on error

Return type

bool

Examples

Class Method:

>>> import mage
>>> mage.connect()
>>> mage.Assessment.create_schedule('DAILY', {'hour':'23', 'minute':'55'}, '11111111-1111-1111-1111-111111111111')

Instance Method:

>>> import mage
>>> mage.connect()
>>> assessment = mage.Assessment.eq(name='My Cloud Test')[0]
>>> assessment.create_schedule('DAILY', {'hour':'23', 'minute':'55'})
>>> assessment.create_schedule('WEEKLY', {'hour':'23', 'minute':'55', 'day_of_week': '1'})
>>> assessment.create_schedule('MONTHLY', {'hour':'23', 'minute':'55', 'day_of_month': '1'})
>>> assessment.create_schedule('QUARTERLY', {'hour':'23', 'minute':'55'})
>>> assessment.create_schedule('YEARLY', {'hour':'23', 'minute':'55', 'day_of_month': '15', 'month': '1'})

classmethod delete_schedule(assessment_id=None)¶

Stops the assessment from repeatedly running.

Parameters: assessment_id (str, optional) – Assessment ID to unschedule.
Returns: True on success, False on error
Return type: bool

Examples

Class Method:

>>> import mage
>>> mage.connect()
>>> mage.Assessment.delete_schedule('11111111-1111-1111-1111-111111111111')

Instance Method:

>>> import mage
>>> mage.connect()
>>> assessment = mage.Assessment.eq(name='My Cloud Test')[0]
>>> assessment.delete_schedule()

load_assets(obj)¶

Loads assets into the assessment. If an asset already exists (due to another assessment) then the existing asset will be used instead of creating a duplicate one.

This method supports the following JSON format, where values can be either arrays or strings depending on how many values there are:

{“cidrs”:”192.168.1.0/24”, “ips”:[“10.10.10.1”, “10.10.10.2”], “domains”: [“www.example.com”, “smtp.example.com”], “emails”: “administrator@example.com”, “cloud_credentials”: []}

Parameters: obj – dict or file-like object or file name
Returns: None

Example

>>> import mage
>>> mage.connect()
>>> assessment = mage.Assessment.eq(name='My Cloud Test')[0]
>>> assessment.load_assets({'ips': '10.10.10.1'})
>>> assessment.load_assets("assets.json")

property runs¶

The list of assessment runs associated with this assessment.

Returns: ListObject of mage.api_resources.assessment_run.AssessmentRun

property runs_filter¶

The list of assessment runs associated with this assessment.

Returns: Filter Object
Return type: mage.api_resources.abstract.filterable_api_resource.Filter

Example

>>> import mage
>>> mage.connect()
>>> assessment = mage.Assessment.eq(name='My Cloud Test')[0]
>>> lastrun = assessment.runs_filter.last()[0]

classmethod start(assessment_id=None)¶

Starts the assessment.

Parameters: assessment_id (str, optional) – Assessment ID to start
Returns: Assessment run ID
Return type: str

Examples

Class Method:

>>> import mage
>>> mage.connect()
>>> mage.Assessment.start('11111111-1111-1111-1111-111111111111')

Instance Method:

>>> import mage
>>> mage.connect()
>>> assessment = mage.Assessment.eq(name='My Cloud Test')[0]
>>> assessment.start()