Risk Atlas Nexus: Quick Start Guide¶

Dependencies¶

Tip: Ensure you have followed installation instructions for the risk_atlas_nexus library

git clone git@github.com:IBM/risk-atlas-nexus.git
cd risk-atlas-nexus
python -m venv vrisk-atlas-nexus
source vrisk-atlas-nexus/bin/activate
pip install -e .

In [ ]:

# imports
from risk_atlas_nexus.ai_risk_ontology.datamodel.ai_risk_ontology import Risk
from risk_atlas_nexus import RiskAtlasNexus

# imports from risk_atlas_nexus.ai_risk_ontology.datamodel.ai_risk_ontology import Risk from risk_atlas_nexus import RiskAtlasNexus

Risk Atlas Nexus project provides an ontology combining an AI risk view (taxonomies, risks, actions) with an AI model view (AI systems, AI models, model evaluations) into one coherent schema.

AI Risks were collected from IBM Risk Atlas, IBM Granite Guardian, MIT AI Risk Repository, NIST Artificial Intelligence Risk Management Framework: Generative Artificial Intelligence Profile, the AILuminate Benchmark, Credo's Unified Control Framework, and OWASP Top 10 for Large Language Model Applications.

You can use the python library methods to quickly explore available risks, relations and actions, as well as to detect potential risks in your usecase.

Important references:

• LinkML schema documentation
• LinkML instance data for an example knowledge graph

About this notebook¶

This notebook contains three sections. Section 1 showcases the default functionality, while Sections 2-3 exhibit useful configurations.

1. How to use Risk Atlas Nexus with default configuration?

In this section, we demonstrate a default method to use Risk Alas Nexus to explore risks and related risks

2. How to use Risk Atlas Nexus to filter results for specific taxonomy?

We provide guidance on filtering the results for a specific taxonomies. This section highlights the ability to filter the taxonomy content.

3. Bring Your Own Taxonomies/Risks/Actions

Risk Atlas Nexus allows users to define custom Taxonomies/Risks/Actions. In this section, we will show you how to load and configure your own data instances.

1. Use case: Risk Atlas Nexus with default configuration¶

Create a new instance of Risk Atlas Nexus and use it to explore the risks. By default, it loads in all data from data folder

In [ ]:

ran = RiskAtlasNexus() # no args, so default configuration 

all_risks = ran.get_all_risks()
print(f"\n# Total risks available : {len(all_risks)}") # 480

# Let's just print out a few for now
print(f"\n# First 2 risks in list ") 
print(all_risks[:2])

ran = RiskAtlasNexus() # no args, so default configuration all_risks = ran.get_all_risks() print(f"\n# Total risks available : {len(all_risks)}") # 480 # Let's just print out a few for now print(f"\n# First 2 risks in list ") print(all_risks[:2])

1.1 Explore risk object¶

In [ ]:

# Each risk is returned as a pydantic "Risk" object as defined in risk_atlas_nexus.ai_risk_ontology.datamodel.ai_risk_ontology
toxic_risk = ran.get_risk(id='atlas-toxic-output')
print(f"\n# Get a risk by ID, 'atlas-toxic-output'  ") 
print(dict(toxic_risk))

# Explore related risks
print(f"\n# Get full entry for each related risks by ID for 'atlas-toxic-output' ") 
related_risks = ran.get_related_risks(id='atlas-toxic-output')
print(related_risks)

# Each risk is returned as a pydantic "Risk" object as defined in risk_atlas_nexus.ai_risk_ontology.datamodel.ai_risk_ontology toxic_risk = ran.get_risk(id='atlas-toxic-output') print(f"\n# Get a risk by ID, 'atlas-toxic-output' ") print(dict(toxic_risk)) # Explore related risks print(f"\n# Get full entry for each related risks by ID for 'atlas-toxic-output' ") related_risks = ran.get_related_risks(id='atlas-toxic-output') print(related_risks)

1.2 Related risks¶

In [ ]:

# Explore related risks
print(f"\n# Get the related risk ids by ID for 'atlas-toxic-output'") 
related_risk_ids = ran.get_related_risks(id='atlas-toxic-output')
print(related_risk_ids)

# For related risks, maybe you might want the full risk to be returned, instead of just the ID
print(f"\n# Get full entry for each related risks by ID for 'atlas-toxic-output' ") 
related_risks = ran.get_related_risks(id='atlas-toxic-output')
print(related_risks)

# Explore related risks print(f"\n# Get the related risk ids by ID for 'atlas-toxic-output'") related_risk_ids = ran.get_related_risks(id='atlas-toxic-output') print(related_risk_ids) # For related risks, maybe you might want the full risk to be returned, instead of just the ID print(f"\n# Get full entry for each related risks by ID for 'atlas-toxic-output' ") related_risks = ran.get_related_risks(id='atlas-toxic-output') print(related_risks)

1.3 Risk Actions¶

Each risk may have the relationship 'hasRelatedAction', a relationship where an entity relates to an action. We can view all actions available, or drill down into how specific actions are related to a risk.

In [ ]:

all_actions = ran.get_all_actions()
print(f"\n# Total actions available : {len(all_actions)}") # 237

# Let's just print out a few for now
print(f"\n# First 2 actions in list ") 
print(all_actions[:2])

# View an individual action by ID. Each action is returned as a pydantic "Action" object as defined in risk_atlas_nexus.ai_risk_ontology.datamodel.ai_risk_ontology
an_action = ran.get_action_by_id('GV-1.3-001')
print(f"\n# Get an action by ID, 'GV-1.3-001' ") 
print(dict(an_action))

# Get any actions for the IBM risk atlas risk toxic output
print(f"\n# Get the linked actions by ID for 'atlas-toxic-output'") 
actions_for_toxic_output = ran.get_related_actions(id='atlas-toxic-output')
print(actions_for_toxic_output) # 0 expected

# Hmm, no linked actions recorded.  Let's try the related risks?
related_actions = []
related_risks = ran.get_related_risks(id='atlas-toxic-output')
for a_risk in related_risks:
    related_actions.extend(ran.get_related_actions(id=a_risk.id))

print(f"\n# Get the actions for the risks which are marked as related to'atlas-toxic-output'") 
print(related_actions)

all_actions = ran.get_all_actions() print(f"\n# Total actions available : {len(all_actions)}") # 237 # Let's just print out a few for now print(f"\n# First 2 actions in list ") print(all_actions[:2]) # View an individual action by ID. Each action is returned as a pydantic "Action" object as defined in risk_atlas_nexus.ai_risk_ontology.datamodel.ai_risk_ontology an_action = ran.get_action_by_id('GV-1.3-001') print(f"\n# Get an action by ID, 'GV-1.3-001' ") print(dict(an_action)) # Get any actions for the IBM risk atlas risk toxic output print(f"\n# Get the linked actions by ID for 'atlas-toxic-output'") actions_for_toxic_output = ran.get_related_actions(id='atlas-toxic-output') print(actions_for_toxic_output) # 0 expected # Hmm, no linked actions recorded. Let's try the related risks? related_actions = [] related_risks = ran.get_related_risks(id='atlas-toxic-output') for a_risk in related_risks: related_actions.extend(ran.get_related_actions(id=a_risk.id)) print(f"\n# Get the actions for the risks which are marked as related to'atlas-toxic-output'") print(related_actions)

1.4 Risk Controls¶

Each risk may have the relationship 'isDetectedBy', a relationship where a risk, risk source, consequence, or impact is detected by a risk control. We can view all risk controls available, or drill down into how specific controls are related to a risk.

In [ ]:

all_risk_controls = ran.get_all_risk_controls()
print(f"\n# Total risk controls available : {len(all_risk_controls)}") # 13

# Let's just print out a few for now
print(f"\n# First 2 risk controls in list ") 
print(all_risk_controls[:2])

# View an individual risk control by ID. Each risk control is returned as a pydantic "RiskControl" object as defined in risk_atlas_nexus.ai_risk_ontology.datamodel.ai_risk_ontology
a_risk_control = ran.get_risk_control('gg-function-call-detection')
print(f"\n# Get a risk control by ID, 'gg-function-call-detection' ") 
print(dict(a_risk_control))

# Get any risk controls for the IBM risk atlas risk harmful output
print(f"\n# Get the linked risk controls by ID for 'granite-function-call") 
controls_for_granite_function_call = ran.get_related_risk_controls(id='granite-function-call')
print(controls_for_granite_function_call) # 1 expected

all_risk_controls = ran.get_all_risk_controls() print(f"\n# Total risk controls available : {len(all_risk_controls)}") # 13 # Let's just print out a few for now print(f"\n# First 2 risk controls in list ") print(all_risk_controls[:2]) # View an individual risk control by ID. Each risk control is returned as a pydantic "RiskControl" object as defined in risk_atlas_nexus.ai_risk_ontology.datamodel.ai_risk_ontology a_risk_control = ran.get_risk_control('gg-function-call-detection') print(f"\n# Get a risk control by ID, 'gg-function-call-detection' ") print(dict(a_risk_control)) # Get any risk controls for the IBM risk atlas risk harmful output print(f"\n# Get the linked risk controls by ID for 'granite-function-call") controls_for_granite_function_call = ran.get_related_risk_controls(id='granite-function-call') print(controls_for_granite_function_call) # 1 expected

2. Use case: Risk Atlas Nexus results filtered by taxonomies¶

First, we will examine which taxonomies are present.

In [ ]:

all_taxonomies = ran.get_all_taxonomies()
print(f"\n# Total taxonomies available : {len(all_taxonomies)}") # 8
print(f"\n# Taxonomy IDs available : {[taxonomy.id for taxonomy in all_taxonomies]}") # 8

# Let's just print out a few for now
print(f"\n# First 2 taxonomies in list ") 
print(all_taxonomies[:2])

# View an individual taxonomy by ID. Each taxonomy is returned as a pydantic "RiskTaxonomy" object as defined in risk_atlas_nexus.ai_risk_ontology.datamodel.ai_risk_ontology
a_taxonomy = ran.get_taxonomy_by_id('nist-ai-rmf')
print(f"\n# Get a taxonomy by ID, 'nist-ai-rmf' ") 
print(dict(a_taxonomy))

all_taxonomies = ran.get_all_taxonomies() print(f"\n# Total taxonomies available : {len(all_taxonomies)}") # 8 print(f"\n# Taxonomy IDs available : {[taxonomy.id for taxonomy in all_taxonomies]}") # 8 # Let's just print out a few for now print(f"\n# First 2 taxonomies in list ") print(all_taxonomies[:2]) # View an individual taxonomy by ID. Each taxonomy is returned as a pydantic "RiskTaxonomy" object as defined in risk_atlas_nexus.ai_risk_ontology.datamodel.ai_risk_ontology a_taxonomy = ran.get_taxonomy_by_id('nist-ai-rmf') print(f"\n# Get a taxonomy by ID, 'nist-ai-rmf' ") print(dict(a_taxonomy))

We will look at the risks which are coming from NIST AI Risk Management Framework (AI RMF)

In [ ]:

all_nist_risks = ran.get_all_risks(taxonomy='nist-ai-rmf')
print(f"\n# Total risks available : {len(all_risks)}") # 480
print(f"\n# Total NIST risks available : {len(all_nist_risks)}") # 12

# Let's just print out a few for now
print(f"\n# First 2 risks in NIST risk list ") 
print(all_nist_risks[:2])

all_nist_risks = ran.get_all_risks(taxonomy='nist-ai-rmf') print(f"\n# Total risks available : {len(all_risks)}") # 480 print(f"\n# Total NIST risks available : {len(all_nist_risks)}") # 12 # Let's just print out a few for now print(f"\n# First 2 risks in NIST risk list ") print(all_nist_risks[:2])

In [ ]:

ran.get_all_risks(taxonomy='ai-risk-taxonomy')

ran.get_all_risks(taxonomy='ai-risk-taxonomy')

3. Usecase: Bring Your Own Taxonomies/Risks/Actions¶

You can add your own risk definitions by adding yaml to your own directory and providing the path as an argument to the RAN when creating it.
Ensure the risks comply with the schema

3.1 Add your YAML definitions¶

Add one or more yaml files to your chosen directory. For example, to add a new risk, create a file with the following content .

- id: my-own-risk
  name: A very risky AI behaviour
  description: An LLM-based system is often very risky
  isDefinedByTaxonomy: my-taxonomy

In [ ]:

# Create an instance which extends the graph with your custom definitions
my_base_dir='<my_user_input_dir_path>'
my_extended_ran = RiskAtlasNexus(base_dir=my_base_dir)
my_extended_risks = my_extended_ran.get_all_risks()
print(f"\n# Total risks available : {len(my_extended_risks)}") 

# Create an instance which extends the graph with your custom definitions my_base_dir='' my_extended_ran = RiskAtlasNexus(base_dir=my_base_dir) my_extended_risks = my_extended_ran.get_all_risks() print(f"\n# Total risks available : {len(my_extended_risks)}")

3.2 Exporting your graph¶

You may wish to export your extended graph.

In [ ]:

# Export the total graph
my_output_dir='<my_output_dir_path>'
my_extended_ran.export(my_output_dir)
print(f"\n# Graph exported to: {my_output_dir}") 

# Check your risk is in the graph
my_risk = ran.get_risk(id='my-own-risk')
print(f"\n# Get my own risk by ID, 'my-own-risk'  ") 
print(dict(my_risk))

# Export the total graph my_output_dir='' my_extended_ran.export(my_output_dir) print(f"\n# Graph exported to: {my_output_dir}") # Check your risk is in the graph my_risk = ran.get_risk(id='my-own-risk') print(f"\n# Get my own risk by ID, 'my-own-risk' ") print(dict(my_risk))