diff --git a/cartography/util.py b/cartography/util.py index 5fb6c1f791..f4c56d4a3a 100644 --- a/cartography/util.py +++ b/cartography/util.py @@ -45,6 +45,14 @@ def run_analysis_job( common_job_parameters: Dict, package: str = 'cartography.data.jobs.analysis', ) -> None: + """ + Enriches existing graph data with analysis jobs. This is designed for use with the sync stage + cartography.intel.analysis. + Runs the queries in the given Python `package` directory (cartography.data.jobs.analysis by default) for the given + `filename`. All queries in this directory are intended to be run at the end of a full graph sync. As such, they are + not scoped to a single sub resource. That is they will apply to _all_ AWS accounts/_all_ GCP projects/_all_ Okta + organizations/etc. + """ GraphJob.run_from_json( neo4j_session, read_text( @@ -61,6 +69,11 @@ def run_scoped_analysis_job( neo4j_session: neo4j.Session, common_job_parameters: Dict, ) -> None: + """ + Enriches existing graph data scoped to a given sub resource - e.g. the current AWS account. + Runs the queries in the cartography.data.jobs.scoped_analysis directory for the given `filename`. View the queries + in cartography.data.jobs.scoped_analysis for specifics. + """ GraphJob.run_from_json( neo4j_session, read_text('cartography.data.jobs.scoped_analysis', filename), diff --git a/docs/root/usage/tutorial.md b/docs/root/usage/tutorial.md index f0cb52fa9b..9e3d95a2f3 100644 --- a/docs/root/usage/tutorial.md +++ b/docs/root/usage/tutorial.md @@ -150,7 +150,7 @@ If you want to learn more in depth about Neo4j and Cypher queries you can look a .. _data-augmentation: -Cartography adds custom attributes to nodes and relationships to point out security-related items of interest. Unless mentioned otherwise these data augmentation jobs are stored in `cartography/data/jobs/analysis`. Here is a summary of all of Cartography's custom attributes. +Cartography adds custom attributes to nodes and relationships to point out security-related items of interest. Data augmentation jobs meant to apply to the whole graph and run at the end of a sync are stored in `cartography/data/jobs/analysis`. Jobs that are meant to apply to a subset of the graph - say, the current AWS account - are stored in `cartography/data/jobs/scoped_analysis`. Here is a summary of all of Cartography's custom attributes. - `exposed_internet` indicates whether the asset is accessible to the public internet.