Update documentation

OTRF · Jan 15, 2024 · a1cab60 · a1cab60
1 parent 9a834c8
commit a1cab60
Show file tree

Hide file tree

Showing 24 changed files with 2,969 additions and 7 deletions.
diff --git a/README.html b/README.html
@@ -187,6 +187,8 @@
 <li class="toctree-l1"><a class="reference internal" href="experiments/RAG/Threat-Intelligence/ATTCK-Groups/LangChain/notebook.html">RAG - LangChain and ATT&amp;CK Groups</a></li>
 <li class="toctree-l1"><a class="reference internal" href="experiments/RAG/Threat-Intelligence/ATTCK-Groups/AutoGen/notebook.html">RAG - AutoGen and ATT&amp;CK Groups</a></li>
 <li class="toctree-l1"><a class="reference internal" href="experiments/Agents/CoT/Local-CoT-Ollama-LiteLLM-Zephyr.html">CoT Reasoning: Chatting with Zephyr 7b Beta</a></li>
+<li class="toctree-l1"><a class="reference internal" href="experiments/ExternalAPIs/MSGraph/OAI-CreateUsers-Arguments.html">Explore MS Graph API to Create a User</a></li>
+<li class="toctree-l1"><a class="reference internal" href="experiments/ExternalAPIs/MSGraph/OAI-MSGraph-Users-Agent.html">A MS Graph API (Users) Agent</a></li>
 <li class="toctree-l1"><a class="reference internal" href="experiments/Bloodhound-GPT/notebook.html">Bloodhound GPT</a></li>
 <li class="toctree-l1"><a class="reference internal" href="experiments/Local-GPT/notebook.html">Local Experiment: GPT4All</a></li>
 <li class="toctree-l1"><a class="reference internal" href="experiments/ROADTools-GPT/notebook.html">ROADTools GPT</a></li>

diff --git a/_sources/experiments/ExternalAPIs/MSGraph/OAI-CreateUsers-Arguments.ipynb b/_sources/experiments/ExternalAPIs/MSGraph/OAI-CreateUsers-Arguments.ipynb
diff --git a/_sources/experiments/ExternalAPIs/MSGraph/OAI-MSGraph-Users-Agent.ipynb b/_sources/experiments/ExternalAPIs/MSGraph/OAI-MSGraph-Users-Agent.ipynb
@@ -0,0 +1,359 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# A MS Graph API (Users) Agent\n",
+    "---\n",
+    "* Collaborators:\n",
+    "    * Roberto Rodriguez (@Cyb3rWard0g)\n",
+    "* References:\n",
+    "    * https://python.langchain.com/docs/use_cases/apis\n",
+    "    * https://python.langchain.com/docs/integrations/toolkits/openapi\n",
+    "    * https://learn.microsoft.com/en-us/graph/api/resources/users?view=graph-rest-1.0"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Download MS Graph (User) OpenAPI specification\n",
+    "\n",
+    "Location: https://github.com/microsoftgraph/msgraph-sdk-powershell/blob/dev/openApiDocs/v1.0/Users.yml"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Load Open API Specification"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "import yaml\n",
+    "from langchain.agents.agent_toolkits.openapi.spec import reduce_openapi_spec\n",
+    "\n",
+    "current_directory = os.path.abspath('')\n",
+    "data_directory = os.path.join(current_directory, \"data\")\n",
+    "msgraph_api_file = os.path.join(data_directory, \"OpenAPI-MSGraph-v1.0-Users.yml\")\n",
+    "\n",
+    "raw_msgraph_api_spec = yaml.load(open(msgraph_api_file,encoding='utf-8').read(), Loader=yaml.Loader)\n",
+    "msgraph_api_spec = reduce_openapi_spec(raw_msgraph_api_spec,dereference=False)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Define LangChain Authorization Header Function"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from azure.identity import InteractiveBrowserCredential\n",
+    "from langchain.requests import RequestsWrapper\n",
+    "\n",
+    "def construct_auth_headers(raw_spec: dict):\n",
+    "    credential = InteractiveBrowserCredential()\n",
+    "    access_token = (credential.get_token(\"https://graph.microsoft.com/.default\")).token\n",
+    "    return {\"Authorization\": f\"Bearer {access_token}\"}\n",
+    "\n",
+    "\n",
+    "# Get API credentials.\n",
+    "headers = construct_auth_headers(raw_msgraph_api_spec)\n",
+    "requests_wrapper = RequestsWrapper(headers=headers)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## MS Graph API Spec"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "140"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "endpoints = [\n",
+    "    (route, operation)\n",
+    "    for route, operations in raw_msgraph_api_spec[\"paths\"].items()\n",
+    "    for operation in operations\n",
+    "    if operation in [\"get\", \"post\"]\n",
+    "]\n",
+    "len(endpoints)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Initialize Open AI Key"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "from dotenv import load_dotenv\n",
+    "import openai\n",
+    "\n",
+    "# Get your key: https://platform.openai.com/account/api-keys\n",
+    "load_dotenv()\n",
+    "openai.api_key = os.getenv(\"OPENAI_API_KEY\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Define OpenAI Chat API"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from langchain.chat_models import ChatOpenAI\n",
+    "from langchain.agents.agent_toolkits.openapi import planner\n",
+    "\n",
+    "llm = ChatOpenAI(model_name=\"gpt-4\", temperature=0.0)\n",
+    "msgraph_agent = planner.create_openapi_agent(msgraph_api_spec, requests_wrapper, llm)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Run Query"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "\n",
+      "\u001b[1m> Entering new AgentExecutor chain...\u001b[0m\n",
+      "\u001b[32;1m\u001b[1;3mAction: api_planner\n",
+      "Action Input: Search for user with id 3b83a100-f4b1-4b9a-934e-5626c7c00dbd\u001b[0m\n",
+      "Observation: \u001b[36;1m\u001b[1;3m1. GET /users/{user-id} to retrieve the properties and relationships of the user with the id 3b83a100-f4b1-4b9a-934e-5626c7c00dbd.\u001b[0m\n",
+      "Thought:\u001b[32;1m\u001b[1;3mI'm ready to execute the API call.\n",
+      "Action: api_controller\n",
+      "Action Input: GET /users/{user-id} to retrieve the properties and relationships of the user with the id 3b83a100-f4b1-4b9a-934e-5626c7c00dbd.\u001b[0m\n",
+      "\n",
+      "\u001b[1m> Entering new AgentExecutor chain...\u001b[0m\n",
+      "\u001b[32;1m\u001b[1;3mI need to use the requests_get tool to make a GET request to the /users/{user-id} endpoint of the API. The user-id is 3b83a100-f4b1-4b9a-934e-5626c7c00dbd. I don't need any parameters for this request. I will extract the id and name from the response.\n",
+      "\n",
+      "Action: requests_get\n",
+      "Action Input: \n",
+      "{\n",
+      "  \"url\": \"https://graph.microsoft.com/v1.0/users/3b83a100-f4b1-4b9a-934e-5626c7c00dbd\",\n",
+      "  \"params\": {},\n",
+      "  \"output_instructions\": {\n",
+      "    \"id\": \"id\",\n",
+      "    \"name\": \"displayName\"\n",
+      "  }\n",
+      "}\n",
+      "\u001b[0m\n",
+      "Observation: \u001b[36;1m\u001b[1;3m{'id': '3b83a100-f4b1-4b9a-934e-5626c7c00dbd', 'name': 'Cyb3rWard0g'}\u001b[0m\n",
+      "Thought:\u001b[32;1m\u001b[1;3mI have successfully retrieved the user's id and name. The user's id is 3b83a100-f4b1-4b9a-934e-5626c7c00dbd and the name is Cyb3rWard0g. I have completed the plan.\n",
+      "\n",
+      "Final Answer: {'id': '3b83a100-f4b1-4b9a-934e-5626c00dbd', 'name': 'Cyb3rWard0g'}\u001b[0m\n",
+      "\n",
+      "\u001b[1m> Finished chain.\u001b[0m\n",
+      "\n",
+      "Observation: \u001b[33;1m\u001b[1;3m{'id': '3b83a100-f4b1-4b9a-934e-5626c00dbd', 'name': 'Cyb3rWard0g'}\u001b[0m\n",
+      "Thought:\u001b[32;1m\u001b[1;3mI am finished executing the plan and have the information the user asked for.\n",
+      "Final Answer: The user with id 3b83a100-f4b1-4b9a-934e-5626c7c00dbd is named 'Cyb3rWard0g'.\u001b[0m\n",
+      "\n",
+      "\u001b[1m> Finished chain.\u001b[0m\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "\"The user with id 3b83a100-f4b1-4b9a-934e-5626c7c00dbd is named 'Cyb3rWard0g'.\""
+      ]
+     },
+     "execution_count": 6,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "user_query = (\n",
+    "    \"Search for user with id 3b83a100-f4b1-4b9a-934e-5626c7c00dbd\"\n",
+    ")\n",
+    "msgraph_agent.run(user_query)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## One Cell Execution"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "\n",
+      "\u001b[1m> Entering new AgentExecutor chain...\u001b[0m\n",
+      "\u001b[32;1m\u001b[1;3mAction: api_planner\n",
+      "Action Input: Search for user with id 3b83a100-f4b1-4b9a-934e-5626c7c00dbd\u001b[0m\n",
+      "Observation: \u001b[36;1m\u001b[1;3m1. GET /users/{user-id} to retrieve the properties and relationships of the user with the id 3b83a100-f4b1-4b9a-934e-5626c7c00dbd.\u001b[0m\n",
+      "Thought:\u001b[32;1m\u001b[1;3mI'm ready to execute the API call.\n",
+      "Action: api_controller\n",
+      "Action Input: GET /users/{user-id} to retrieve the properties and relationships of the user with the id 3b83a100-f4b1-4b9a-934e-5626c7c00dbd.\u001b[0m\n",
+      "\n",
+      "\u001b[1m> Entering new AgentExecutor chain...\u001b[0m\n",
+      "\u001b[32;1m\u001b[1;3mI need to use the requests_get tool to make a GET request to the /users/{user-id} endpoint of the API. The user-id in the path should be replaced with the actual user id.\n",
+      "\n",
+      "Action: requests_get\n",
+      "Action Input: \n",
+      "{\n",
+      "  \"url\": \"https://graph.microsoft.com/v1.0/users/3b83a100-f4b1-4b9a-934e-5626c7c00dbd\",\n",
+      "  \"params\": {},\n",
+      "  \"output_instructions\": \"Extract the id and name of the user\"\n",
+      "}\u001b[0m\n",
+      "Observation: \u001b[36;1m\u001b[1;3mThe user's ID is \"3b83a100-f4b1-4b9a-934e-5626c7c00dbd\" and the name is \"Cyb3rWard0g\".\u001b[0m\n",
+      "Thought:\u001b[32;1m\u001b[1;3mI have successfully retrieved the user's information. The plan has been executed successfully.\n",
+      "Final Answer: The user's ID is \"3b83a100-f4b1-4b9a-934e-5626c7c00dbd\" and the name is \"Cyb3rWard0g\".\u001b[0m\n",
+      "\n",
+      "\u001b[1m> Finished chain.\u001b[0m\n",
+      "\n",
+      "Observation: \u001b[33;1m\u001b[1;3mThe user's ID is \"3b83a100-f4b1-4b9a-934e-5626c7c00dbd\" and the name is \"Cyb3rWard0g\".\u001b[0m\n",
+      "Thought:\u001b[32;1m\u001b[1;3mI am finished executing the plan and have the information the user asked for.\n",
+      "Final Answer: The user's ID is \"3b83a100-f4b1-4b9a-934e-5626c7c00dbd\" and the name is \"Cyb3rWard0g\".\u001b[0m\n",
+      "\n",
+      "\u001b[1m> Finished chain.\u001b[0m\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "'The user\\'s ID is \"3b83a100-f4b1-4b9a-934e-5626c7c00dbd\" and the name is \"Cyb3rWard0g\".'"
+      ]
+     },
+     "execution_count": 7,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# Download MS Graph API OpenAPI Specification:\n",
+    "#  https://github.com/microsoftgraph/msgraph-sdk-powershell/blob/dev/openApiDocs/v1.0/Users.yml\n",
+    "import os\n",
+    "import yaml\n",
+    "from langchain.agents.agent_toolkits.openapi.spec import reduce_openapi_spec\n",
+    "\n",
+    "# Read File Locally\n",
+    "current_directory = os.path.abspath('')\n",
+    "msgraph_api_file = os.path.join('data', \"OpenAPI-MSGraph-v1.0-Users.yml\")\n",
+    "raw_msgraph_api_spec = yaml.load(open(msgraph_api_file,encoding='utf-8').read(), Loader=yaml.Loader)\n",
+    "\n",
+    "# Read as OpenAPI Specification\n",
+    "msgraph_api_spec = reduce_openapi_spec(raw_msgraph_api_spec,dereference=False)\n",
+    "\n",
+    "# Define LangChain Authorization Header Function \n",
+    "from azure.identity import InteractiveBrowserCredential\n",
+    "from langchain.requests import RequestsWrapper\n",
+    "\n",
+    "def construct_auth_headers(raw_spec: dict):\n",
+    "    credential = InteractiveBrowserCredential()\n",
+    "    access_token = (credential.get_token(\"https://graph.microsoft.com/.default\")).token\n",
+    "    return {\"Authorization\": f\"Bearer {access_token}\"}\n",
+    "\n",
+    "# Get Access Token -> Authorization Header.\n",
+    "headers = construct_auth_headers(raw_msgraph_api_spec)\n",
+    "requests_wrapper = RequestsWrapper(headers=headers)\n",
+    "\n",
+    "# Define OpenAI Chat API\n",
+    "from langchain.chat_models import ChatOpenAI\n",
+    "from langchain.agents.agent_toolkits.openapi import planner\n",
+    "from dotenv import load_dotenv\n",
+    "import openai\n",
+    "# Initialize OpenAI Key. Get your key: https://platform.openai.com/account/api-keys\n",
+    "load_dotenv()\n",
+    "openai.api_key = os.getenv(\"OPENAI_API_KEY\")\n",
+    "llm = ChatOpenAI(model_name=\"gpt-4\", temperature=0.0)\n",
+    "\n",
+    "# Create OpenAPI Agent\n",
+    "msgraph_agent = planner.create_openapi_agent(msgraph_api_spec, requests_wrapper, llm)\n",
+    "\n",
+    "# Pass prompt (Natural Language) to Agent -> Call MS Graph API\n",
+    "msgraph_agent.run((\"Search for user with id 3b83a100-f4b1-4b9a-934e-5626c7c00dbd\"))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}