ocinferno 0.5.5__tar.gz

ocinferno-0.5.5/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, NetSPI
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ocinferno-0.5.5/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: ocinferno
+Version: 0.5.5
+Summary: OCI offensive security assessment and enumeration framework.
+Author: NetSPI
+License-Expression: BSD-3-Clause
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Information Technology
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML==6.0.3
+Requires-Dist: oci==2.169.0
+Requires-Dist: requests==2.33.1
+Requires-Dist: prettytable==3.17.0
+Requires-Dist: oci-lexer-parser==0.1.2
+Requires-Dist: pandas==2.3.3; python_version < "3.11"
+Requires-Dist: pandas==3.0.1; python_version >= "3.11"
+Requires-Dist: xlsxwriter==3.2.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# OCInferno
+
+[![Unit Tests](https://img.shields.io/github/actions/workflow/status/NetSPI/OCInferno/ci.yml?branch=main&label=unit%20tests)](https://github.com/NetSPI/OCInferno/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ocinferno)](https://pypi.org/project/ocinferno/)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](./LICENSE)
+[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)](./CONTRIBUTING.md)
+[![OCI SDK](https://img.shields.io/badge/oci--sdk-2.169.0-orange)](https://pypi.org/project/oci/)
+
+## Overview
+
+> In the spirit of transparency: parts of this project and documentation were developed with LLM coding assistance. Review code and behavior in your environment before operational use. Notably, the enum_config_checks module is still in-progress based off original content generated.
+
+OCInferno (O-C-Inferno) is an OCI offensive security assessment framework for workspace-driven credential handling, service enumeration, artifact download, and graph-based attack-path analysis. It includes a module to generate a custom **OpenGraph output** which can be fed into BloodHound, as shown below, to map privilege-escalation paths.
+
+<p align="center" style="margin: 0.35em 0 0 0;">
+  <img src="./images/README_OVERVIEW.png" alt="Sample OpenGraph output in BloodHound" />
+</p>
+<p align="center" style="margin: 0.15em 0 1em 0;"><em>Figure 1. Example OpenGraph/BloodHound relationship view.</em></p>
+
+<p align="center" style="margin: 0.35em 0 0 0;">
+  <img src="./images/MODULE_RUN.png" alt="OCInferno terminal output example" />
+</p>
+<p align="center" style="margin: 0.15em 0 1em 0;"><em>Figure 2. Example module output in the CLI.</em></p>
+
+## High-Level Features
+
+- **CLI UX:** Interactive CLI with command and argument tab auto-complete and history.
+- **Authentication:** Multiple supported auth methods:
+  - **Config Profile:** API key-backed and session-token-backed OCI profiles.
+  - **Instance Principal:** Compute-instance identity flow.
+  - **Resource Principal:** Runtime/workload identity flow.
+- **Module Model:** Service-specific modules across OCI services, with proxy and rate-limiting support.
+- **Mass Enumeration:** Broad OCI module coverage with `enum_all` orchestration support (implemented in `modules/everything`).
+- **Config Audits:** `enum_config_check` findings based on enumerated/saved data (implemented in `modules/everything`).
+- **Reporting Exports:** Resource export support for HTML, CSV, JSON, Excel, and graph image outputs.
+- **Artifact Downloads:** Download support across many modules with `--download` and selective routing.
+- **OpenGraph / BloodHound:** OpenGraph export for BloodHound ingestion, including:
+  - A default focused view of high-impact edges, with `--include-all` available for broader relationship output to ideally see all relationships regardless of priv escalation weight.
+  - Privilege-escalation path modeling across OCI IAM and Identity Domain app-role/grant relationships.
+  - Inheritance-aware modeling (`--expand-inherited`) and conditional evaluation (`--cond-eval`) to improve graph accuracy.
+
+## Documentation
+
+Documentation is maintained on the GitHub Wiki:
+
+- https://github.com/NetSPI/OCInferno/wiki
+
+Contributing guidance:
+
+- `CONTRIBUTING.md`
+
+Roadmap guidance:
+
+- `ROADMAP.md`
+
+Sample OpenGraph JSON:
+
+- `opengraph_examples/example_input.json`
+
+## Installation TLDR
+
+```bash
+git clone https://github.com/NetSPI/OCInferno.git
+
+# You don't need pytests to run the tool
+rm -r tests/
+
+virtualenv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+python -m cli.main
+```
+
+## Launch and Data Download TLDR
+
+Run the tool:
+
+```bash
+python -m cli.main
+```
+
+At startup:
+
+1. Create/select a workspace.
+2. Add credentials using your OCI config profile (example uses `MY_PROFILE` to add an API key):
+```text
+profile MY_PROFILE --filepath ~/.oci/config --profile MY_PROFILE
+```
+3. Start the first full run.
+   `enum_all` runs all modules. `--comp` recursively enumerates compartments to maximize coverage.
+   `--get` follows LIST calls with GET calls where supported for deeper detail.
+   `--download` downloads data where possible, choosing `--not-downloads buckets` attempts to download all content **except** bucket object content.
+```bash
+# Download as much as you can
+modules run enum_all --get --comp --download
+# Download everything EXCEPT bucket contents
+modules run enum_all --get --comp [--not-downloads buckets]
+```
+4. Export a compartment tree image and Excel data output to quickly review what your current permissions can see:
+```bash
+(TENANT-2snxfsaa:TEST)> data export treeimage
+[*] Compartment tree export complete -> ./ocinferno_output/1_TEST/exports/data/global/resource_reports/compartment_tree.svg (format=svg, renderer=svg-interactive, compartments=6)
+
+(TENANT-2snxfsaa:TEST)> data export excel
+[*] Excel export complete -> ./ocinferno_output/1_TEST/exports/data/global/sqlite_excel/sqlite_blob.xlsx (format=xlsx, databases=1, tables=173, rows=54951, single_sheet=True, condensed=True)
+
+```
+
+<p align="center" style="margin: 0.35em 0 0 0;">
+  <img src="./images/COMP_HIERARCHY_1.png" alt="Compartment Tree Export" />
+</p>
+<p align="center" style="margin: 0.15em 0 1em 0;"><em>Figure 1. Tree image export from <code>data export treeimage</code>.</em></p>
+
+<p align="center" style="margin: 0.35em 0 0 0;">
+  <img src="./images/DATA_EXPORT_1.png" alt="Excel Data Export" />
+</p>
+<p align="center" style="margin: 0.15em 0 1em 0;"><em>Figure 2. Excel export output from <code>data export excel</code>.</em></p>
+
+## OpenGraph TLDR
+
+### Where JSON is saved
+
+Once all data is collected, use the `enum_oracle_cloud_hound_data` module as seen in example below:
+```bash
+modules run enum_oracle_cloud_hound_data [--include-all] [--expand-inherited] [--cond-eval] --reset  --out opengraph_output.json
+```
+Optional OpenGraph flags:
+
+- `[--include-all]`: include broader non-default relationship output, not just default high-impact allowlist-focused edges.
+- `[--expand-inherited]`: expand inherited IAM scope/location relationships.
+- `[--cond-eval]`: evaluate IAM statement conditions (when resolvable) to improve edge accuracy.
+- `[--reset]`: Wipes Opengraph database before creating JSON. Advised to always run this if you want a fresh generation each time else there might be legacy content from past runs.
+
+### Import into BloodHound
+
+1. Open BloodHound CE. Installation instructions can be found [here](https://bloodhound.specterops.io/get-started/quickstart/community-edition-quickstart)
+2. Go to data import.
+3. Upload `oracle_cloud_hound.json`.
+4. Run path queries against high-impact OCI edges.
+
+<p align="center" style="margin: 0.35em 0 0 0;">
+  <img src="./images/BLOODHOUND_UPLOAD.png" alt="BloodHound upload workflow for oracle_cloud_hound.json" />
+</p>
+<p align="center" style="margin: 0.15em 0 1em 0;"><em>Figure 3. Uploading OpenGraph JSON into BloodHound CE.</em></p>
+
+### Sample Cypher Queries
+
+```cypher
+// 0) See All nodes and edges
+MATCH (n)
+OPTIONAL MATCH (n)-[r]-(m)
+RETURN n, r, m
+
+// 1) Find all users not in any group
+MATCH (u:OCIUser)
+WHERE NOT (u)-[:OCI_GROUP_MEMBER]->(:OCIGroup)
+RETURN u
+ORDER BY coalesce(u.name, u.id);
+
+// 2a) Find standard groups with no members
+MATCH (g:OCIGroup)
+WHERE NOT (:OCIUser)-[:OCI_GROUP_MEMBER]->(g)
+RETURN g
+ORDER BY coalesce(g.name, g.id);
+
+// 2b) Find dynamic groups with no matched members
+MATCH (dg:OCIDynamicGroup)
+WHERE NOT ()-[:OCI_DYNAMIC_GROUP_MEMBER]->(dg)
+RETURN dg
+ORDER BY coalesce(dg.name, dg.id);
+
+// 3) Find all paths from all principals to all-resources scopes (depth 1..6)
+MATCH (p0)
+WHERE p0:OCIUser OR p0:OCIGroup OR p0:OCIDynamicGroup
+MATCH p = (p0)-[*1..6]->(r:OCIAllResources)
+RETURN p
+LIMIT 500;
+
+// 4) Find all paths to all-resources scopes regardless of start node type (depth 1..6)
+MATCH p = (s)-[*1..6]->(r:OCIAllResources)
+RETURN p
+LIMIT 500;
+```
+
+### Add a custom allowlist edge (TLDR)
+
+If you want to add your own default OpenGraph edge (for example tie `GROUP_INSPECT` to an edge), add a rule in:
+
+- `modules/opengraph/utilities/helpers/data/static_constants.json` under `ALLOW_RULE_DEFS`
+
+Example:
+
+```json
+{
+  "id": "GROUP_INSPECT",
+  "match": {
+    "resource_tokens": ["groups"],
+    "permissions_all": ["GROUP_INSPECT"]
+  },
+  "edge": {
+    "label": "OCI_GROUP_INSPECT",
+    "description": "Inspect IAM groups in scope."
+  },
+  "destination": {
+    "token": "groups",
+    "node_type": "OCIResourceGroup",
+    "allow_specific": true
+  }
+}
+```
+
+Field quick reference:
+
+- `id`: internal rule identifier used by the builder/tests.
+- `match.resource_tokens`: OCI policy resource token(s) the statement must target (for example `groups`).
+- `match.permissions_all`: permission(s) that must all be present in the same statement to trigger the edge.
+- `edge.label`: relationship kind written into OpenGraph.
+- `edge.description`: human-readable explanation stored on the edge.
+- `destination.token`: logical destination scope/resource token represented in the graph.
+- `destination.node_type`: node class to emit for the destination (commonly `OCIResourceGroup`).
+- `destination.allow_specific`: when `true`, conditionals can resolve to specific resources (for example a specific group) instead of only generic scope nodes.
+
+Then rerun `enum_oracle_cloud_hound_data` and update tests/golden outputs if behavior changed.
+
+## Dependency Inventory
+
+| Dependency | Where Used | Purpose |
+| --- | --- | --- |
+| `oci==2.169.0` | Core modules | OCI SDK clients/auth/providers for enumeration and actions. |
+| `requests==2.33.1` | HTTP helpers/integrations | HTTP operations and API helper requests. |
+| `PyYAML>=6.0.3` | Config/parsing layers | YAML config and mapping parsing. |
+| `prettytable==3.17.0` | CLI output | Terminal table rendering. |
+| `oci-lexer-parser==0.1.2` | Policy/OpenGraph logic | OCI IAM policy lexing/parsing support. |
+| `pandas>=2.2.0` | Data export | Excel export pipeline. |
+| `xlsxwriter>=3.2.0` | Data export | `.xlsx` writer engine for exports. |
+| `pytest>=8.0`* | Unit tests | Test framework (`tests/unit`). |
+
+*Dev/test-scoped dependency.
+
+## Repository Layout
+
+- `cli/`: interactive command processor and startup flow.
+- `core/`: session, config, data, utility, and logging controllers.
+- `modules/`: service modules plus `Everything` (`enum_all`, `enum_config_check`).
+- `utils/`: shared module utilities and exports.
+- `tests/`: unit tests run in CI.

ocinferno-0.5.5/README.md

@@ -0,0 +1,247 @@
+# OCInferno
+
+[![Unit Tests](https://img.shields.io/github/actions/workflow/status/NetSPI/OCInferno/ci.yml?branch=main&label=unit%20tests)](https://github.com/NetSPI/OCInferno/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ocinferno)](https://pypi.org/project/ocinferno/)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](./LICENSE)
+[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)](./CONTRIBUTING.md)
+[![OCI SDK](https://img.shields.io/badge/oci--sdk-2.169.0-orange)](https://pypi.org/project/oci/)
+
+## Overview
+
+> In the spirit of transparency: parts of this project and documentation were developed with LLM coding assistance. Review code and behavior in your environment before operational use. Notably, the enum_config_checks module is still in-progress based off original content generated.
+
+OCInferno (O-C-Inferno) is an OCI offensive security assessment framework for workspace-driven credential handling, service enumeration, artifact download, and graph-based attack-path analysis. It includes a module to generate a custom **OpenGraph output** which can be fed into BloodHound, as shown below, to map privilege-escalation paths.
+
+<p align="center" style="margin: 0.35em 0 0 0;">
+  <img src="./images/README_OVERVIEW.png" alt="Sample OpenGraph output in BloodHound" />
+</p>
+<p align="center" style="margin: 0.15em 0 1em 0;"><em>Figure 1. Example OpenGraph/BloodHound relationship view.</em></p>
+
+<p align="center" style="margin: 0.35em 0 0 0;">
+  <img src="./images/MODULE_RUN.png" alt="OCInferno terminal output example" />
+</p>
+<p align="center" style="margin: 0.15em 0 1em 0;"><em>Figure 2. Example module output in the CLI.</em></p>
+
+## High-Level Features
+
+- **CLI UX:** Interactive CLI with command and argument tab auto-complete and history.
+- **Authentication:** Multiple supported auth methods:
+  - **Config Profile:** API key-backed and session-token-backed OCI profiles.
+  - **Instance Principal:** Compute-instance identity flow.
+  - **Resource Principal:** Runtime/workload identity flow.
+- **Module Model:** Service-specific modules across OCI services, with proxy and rate-limiting support.
+- **Mass Enumeration:** Broad OCI module coverage with `enum_all` orchestration support (implemented in `modules/everything`).
+- **Config Audits:** `enum_config_check` findings based on enumerated/saved data (implemented in `modules/everything`).
+- **Reporting Exports:** Resource export support for HTML, CSV, JSON, Excel, and graph image outputs.
+- **Artifact Downloads:** Download support across many modules with `--download` and selective routing.
+- **OpenGraph / BloodHound:** OpenGraph export for BloodHound ingestion, including:
+  - A default focused view of high-impact edges, with `--include-all` available for broader relationship output to ideally see all relationships regardless of priv escalation weight.
+  - Privilege-escalation path modeling across OCI IAM and Identity Domain app-role/grant relationships.
+  - Inheritance-aware modeling (`--expand-inherited`) and conditional evaluation (`--cond-eval`) to improve graph accuracy.
+
+## Documentation
+
+Documentation is maintained on the GitHub Wiki:
+
+- https://github.com/NetSPI/OCInferno/wiki
+
+Contributing guidance:
+
+- `CONTRIBUTING.md`
+
+Roadmap guidance:
+
+- `ROADMAP.md`
+
+Sample OpenGraph JSON:
+
+- `opengraph_examples/example_input.json`
+
+## Installation TLDR
+
+```bash
+git clone https://github.com/NetSPI/OCInferno.git
+
+# You don't need pytests to run the tool
+rm -r tests/
+
+virtualenv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+python -m cli.main
+```
+
+## Launch and Data Download TLDR
+
+Run the tool:
+
+```bash
+python -m cli.main
+```
+
+At startup:
+
+1. Create/select a workspace.
+2. Add credentials using your OCI config profile (example uses `MY_PROFILE` to add an API key):
+```text
+profile MY_PROFILE --filepath ~/.oci/config --profile MY_PROFILE
+```
+3. Start the first full run.
+   `enum_all` runs all modules. `--comp` recursively enumerates compartments to maximize coverage.
+   `--get` follows LIST calls with GET calls where supported for deeper detail.
+   `--download` downloads data where possible, choosing `--not-downloads buckets` attempts to download all content **except** bucket object content.
+```bash
+# Download as much as you can
+modules run enum_all --get --comp --download
+# Download everything EXCEPT bucket contents
+modules run enum_all --get --comp [--not-downloads buckets]
+```
+4. Export a compartment tree image and Excel data output to quickly review what your current permissions can see:
+```bash
+(TENANT-2snxfsaa:TEST)> data export treeimage
+[*] Compartment tree export complete -> ./ocinferno_output/1_TEST/exports/data/global/resource_reports/compartment_tree.svg (format=svg, renderer=svg-interactive, compartments=6)
+
+(TENANT-2snxfsaa:TEST)> data export excel
+[*] Excel export complete -> ./ocinferno_output/1_TEST/exports/data/global/sqlite_excel/sqlite_blob.xlsx (format=xlsx, databases=1, tables=173, rows=54951, single_sheet=True, condensed=True)
+
+```
+
+<p align="center" style="margin: 0.35em 0 0 0;">
+  <img src="./images/COMP_HIERARCHY_1.png" alt="Compartment Tree Export" />
+</p>
+<p align="center" style="margin: 0.15em 0 1em 0;"><em>Figure 1. Tree image export from <code>data export treeimage</code>.</em></p>
+
+<p align="center" style="margin: 0.35em 0 0 0;">
+  <img src="./images/DATA_EXPORT_1.png" alt="Excel Data Export" />
+</p>
+<p align="center" style="margin: 0.15em 0 1em 0;"><em>Figure 2. Excel export output from <code>data export excel</code>.</em></p>
+
+## OpenGraph TLDR
+
+### Where JSON is saved
+
+Once all data is collected, use the `enum_oracle_cloud_hound_data` module as seen in example below:
+```bash
+modules run enum_oracle_cloud_hound_data [--include-all] [--expand-inherited] [--cond-eval] --reset  --out opengraph_output.json
+```
+Optional OpenGraph flags:
+
+- `[--include-all]`: include broader non-default relationship output, not just default high-impact allowlist-focused edges.
+- `[--expand-inherited]`: expand inherited IAM scope/location relationships.
+- `[--cond-eval]`: evaluate IAM statement conditions (when resolvable) to improve edge accuracy.
+- `[--reset]`: Wipes Opengraph database before creating JSON. Advised to always run this if you want a fresh generation each time else there might be legacy content from past runs.
+
+### Import into BloodHound
+
+1. Open BloodHound CE. Installation instructions can be found [here](https://bloodhound.specterops.io/get-started/quickstart/community-edition-quickstart)
+2. Go to data import.
+3. Upload `oracle_cloud_hound.json`.
+4. Run path queries against high-impact OCI edges.
+
+<p align="center" style="margin: 0.35em 0 0 0;">
+  <img src="./images/BLOODHOUND_UPLOAD.png" alt="BloodHound upload workflow for oracle_cloud_hound.json" />
+</p>
+<p align="center" style="margin: 0.15em 0 1em 0;"><em>Figure 3. Uploading OpenGraph JSON into BloodHound CE.</em></p>
+
+### Sample Cypher Queries
+
+```cypher
+// 0) See All nodes and edges
+MATCH (n)
+OPTIONAL MATCH (n)-[r]-(m)
+RETURN n, r, m
+
+// 1) Find all users not in any group
+MATCH (u:OCIUser)
+WHERE NOT (u)-[:OCI_GROUP_MEMBER]->(:OCIGroup)
+RETURN u
+ORDER BY coalesce(u.name, u.id);
+
+// 2a) Find standard groups with no members
+MATCH (g:OCIGroup)
+WHERE NOT (:OCIUser)-[:OCI_GROUP_MEMBER]->(g)
+RETURN g
+ORDER BY coalesce(g.name, g.id);
+
+// 2b) Find dynamic groups with no matched members
+MATCH (dg:OCIDynamicGroup)
+WHERE NOT ()-[:OCI_DYNAMIC_GROUP_MEMBER]->(dg)
+RETURN dg
+ORDER BY coalesce(dg.name, dg.id);
+
+// 3) Find all paths from all principals to all-resources scopes (depth 1..6)
+MATCH (p0)
+WHERE p0:OCIUser OR p0:OCIGroup OR p0:OCIDynamicGroup
+MATCH p = (p0)-[*1..6]->(r:OCIAllResources)
+RETURN p
+LIMIT 500;
+
+// 4) Find all paths to all-resources scopes regardless of start node type (depth 1..6)
+MATCH p = (s)-[*1..6]->(r:OCIAllResources)
+RETURN p
+LIMIT 500;
+```
+
+### Add a custom allowlist edge (TLDR)
+
+If you want to add your own default OpenGraph edge (for example tie `GROUP_INSPECT` to an edge), add a rule in:
+
+- `modules/opengraph/utilities/helpers/data/static_constants.json` under `ALLOW_RULE_DEFS`
+
+Example:
+
+```json
+{
+  "id": "GROUP_INSPECT",
+  "match": {
+    "resource_tokens": ["groups"],
+    "permissions_all": ["GROUP_INSPECT"]
+  },
+  "edge": {
+    "label": "OCI_GROUP_INSPECT",
+    "description": "Inspect IAM groups in scope."
+  },
+  "destination": {
+    "token": "groups",
+    "node_type": "OCIResourceGroup",
+    "allow_specific": true
+  }
+}
+```
+
+Field quick reference:
+
+- `id`: internal rule identifier used by the builder/tests.
+- `match.resource_tokens`: OCI policy resource token(s) the statement must target (for example `groups`).
+- `match.permissions_all`: permission(s) that must all be present in the same statement to trigger the edge.
+- `edge.label`: relationship kind written into OpenGraph.
+- `edge.description`: human-readable explanation stored on the edge.
+- `destination.token`: logical destination scope/resource token represented in the graph.
+- `destination.node_type`: node class to emit for the destination (commonly `OCIResourceGroup`).
+- `destination.allow_specific`: when `true`, conditionals can resolve to specific resources (for example a specific group) instead of only generic scope nodes.
+
+Then rerun `enum_oracle_cloud_hound_data` and update tests/golden outputs if behavior changed.
+
+## Dependency Inventory
+
+| Dependency | Where Used | Purpose |
+| --- | --- | --- |
+| `oci==2.169.0` | Core modules | OCI SDK clients/auth/providers for enumeration and actions. |
+| `requests==2.33.1` | HTTP helpers/integrations | HTTP operations and API helper requests. |
+| `PyYAML>=6.0.3` | Config/parsing layers | YAML config and mapping parsing. |
+| `prettytable==3.17.0` | CLI output | Terminal table rendering. |
+| `oci-lexer-parser==0.1.2` | Policy/OpenGraph logic | OCI IAM policy lexing/parsing support. |
+| `pandas>=2.2.0` | Data export | Excel export pipeline. |
+| `xlsxwriter>=3.2.0` | Data export | `.xlsx` writer engine for exports. |
+| `pytest>=8.0`* | Unit tests | Test framework (`tests/unit`). |
+
+*Dev/test-scoped dependency.
+
+## Repository Layout
+
+- `cli/`: interactive command processor and startup flow.
+- `core/`: session, config, data, utility, and logging controllers.
+- `modules/`: service modules plus `Everything` (`enum_all`, `enum_config_check`).
+- `utils/`: shared module utilities and exports.
+- `tests/`: unit tests run in CI.

ocinferno-0.5.5/cli/main.py

@@ -0,0 +1,140 @@
+import argparse
+from typing import List, Tuple, Optional
+import json
+
+from cli.workspace_instructions import workspace_instructions
+from core.db import DataController
+from core.console import UtilityTools
+
+def create_workspace(dc: DataController, workspace_name: str) -> Optional[int]:
+    workspace_name = (workspace_name or "").strip()
+    if workspace_name.isdigit():
+        print(
+            f"{UtilityTools.RED}{UtilityTools.BOLD}[X] Workspace name cannot be numeric-only."
+            f" Use a descriptive name (for example: TEST, PROD, LAB).{UtilityTools.RESET}"
+        )
+        return None
+
+    existing_names = dc.fetch_all_workspace_names()
+    if workspace_name in existing_names:
+        print(f"{UtilityTools.RED}{UtilityTools.BOLD}[X] A workspace with that name already exists.{UtilityTools.RESET}")
+        return None
+
+    starting_config_data = {
+        "proxy": None,
+        "current_default_region": "",
+        "module_auto_save": True,
+    }
+
+    starting_config_data_json_blob = json.dumps(starting_config_data)
+
+    workspace_id = dc.insert_workspace(workspace_name, starting_config_data_json_blob)
+    if workspace_id:
+        print(f"{UtilityTools.GREEN}{UtilityTools.BOLD}[*] Workspace '{workspace_name}' created.{UtilityTools.RESET}")
+        return workspace_id
+
+    print(f"{UtilityTools.RED}{UtilityTools.BOLD}[X] Failed to create workspace.{UtilityTools.RESET}")
+    return None
+
+def prompt_new_workspace(dc: DataController) -> Tuple[str, int]:
+    while True:
+        name = input("> New workspace name: ").strip()
+        if 1 <= len(name) <= 80:
+            workspace_id = create_workspace(dc, name)
+            if workspace_id:
+                return name, workspace_id
+        else:
+            print(f"{UtilityTools.RED}{UtilityTools.BOLD}[X] Name must be between 1 and 80 characters.{UtilityTools.RESET}")
+
+def list_workspaces(workspaces: List[Tuple[int, str]]) -> None:
+    print("[*] Found existing sessions:")
+    print("  [0] Create new workspace")
+    for idx, name in workspaces:
+        print(f"  [{idx}] {name}")
+    print(f"  [{len(workspaces)+1}] Exit")
+
+def choose_workspace(
+    workspaces: List[Tuple[int, str]],
+    dc: DataController,
+    startup_auth_proxy: Optional[str] = None,
+    startup_silent: bool = False,
+) -> None:
+    workspace_map = {idx: name for idx, name in workspaces}
+
+    while True:
+        try:
+            choice = int(input("Choose an option: ").strip())
+            break
+        except ValueError:
+            print("Please enter a valid number.")
+
+    if choice == 0:
+        name, workspace_id = prompt_new_workspace(dc)
+        workspace_instructions(
+            workspace_id,
+            name,
+            startup_auth_proxy=startup_auth_proxy,
+            startup_silent=startup_silent,
+        )
+    elif choice == len(workspaces) + 1:
+        exit()
+    elif choice in workspace_map:
+        workspace_instructions(
+            choice,
+            workspace_map[choice],
+            startup_auth_proxy=startup_auth_proxy,
+            startup_silent=startup_silent,
+        )
+    else:
+        print(f"{UtilityTools.RED}{UtilityTools.BOLD}[X] Invalid workspace selected. Quitting...{UtilityTools.RESET}")
+        exit()
+
+def main() -> None:
+    parser = argparse.ArgumentParser(add_help=True)
+    parser.add_argument(
+        "--auth-proxy",
+        dest="auth_proxy",
+        default=None,
+        help=(
+            "Startup-only proxy for credential auth exchanges during add/load at launch "
+            "(does not apply to module API traffic, set that in configs or per proxy). "
+            "Format: host:port or http(s)://host:port."
+        ),
+    )
+    parser.add_argument(
+        "--silent",
+        action="store_true",
+        help="Start OCInferno without printing the initial help banner.",
+    )
+    args = parser.parse_args()
+
+    dc = DataController()
+    workspaces = dc.get_workspaces()
+
+    # If we have no existing workspaces prompt for a new one
+    if not workspaces:
+        print("[*] No workspaces detected. Please create your first workspace.")
+        name, workspace_id = prompt_new_workspace(dc)
+        workspace_instructions(
+            workspace_id,
+            name,
+            startup_auth_proxy=args.auth_proxy,
+            startup_silent=args.silent,
+        )
+    
+    # If workspaces exist presetn options and have user choose one
+    else:
+        list_workspaces(workspaces)
+        choose_workspace(
+            workspaces,
+            dc,
+            startup_auth_proxy=args.auth_proxy,
+            startup_silent=args.silent,
+        )
+
+if __name__ == "__main__":
+    try:
+        main()
+    except KeyboardInterrupt:
+        print("\n[*] Interrupted. Exiting.")
+        raise SystemExit(130)