Troubleshooting and FAQ

Troubleshooting and FAQ

Common OCInferno setup and runtime issues, with quick fixes. For auth-specific failures see the error table in Authentication Reference.

ocinferno command not found

Run via the module entrypoint instead:

python -m ocinferno

If you installed via pip, confirm you are in the same virtual environment you installed into and that its bin/ is on PATH. The legacy/internal python -m cli.main startup path is deprecated — use ocinferno or python -m ocinferno.

Excel export fails or data export excel does nothing

Excel export is an optional extra (it pulls in pandas + xlsxwriter), lazily imported so a base install stays lean. Install it, then rerun:

pip install "ocinferno[excel]"
data export excel

csv, json, and treeimage exports work in the base install and need no extra. See Data View/Export.

Terminal tables look wrong / I want plain text

Table rendering works out of the box with no extra dependencies. To switch rendering style, set the workspace config:

configs set std_output_format table   # default
configs set std_output_format txt     # plain text

"No compartments discovered yet"

Most service modules fan out per compartment. If OCInferno has not learned the compartment tree yet, enumerate it first, or point the run at specific compartments:

modules run enum_comp                 # discover + persist the compartment tree
compartments list                     # inspect what was found
compartments set                      # pick a current compartment (interactive)

Or scope a single run directly with the runner flags:

modules run enum_identity --current-cid          # only the current compartment
modules run enum_identity --all-cids             # all discovered compartments
modules run enum_identity --cids ocid1.compartment.oc1..COMPARTMENT_ID

"NotAuthorizedOrNotFound" / 403 / empty results for a service

OCI returns NotAuthorizedOrNotFound for both missing permissions and missing resources. Empty enumeration usually means the current principal's effective permissions (via IAM policy and, for instance/resource principals, dynamic-group membership) do not grant read/inspect on that service in that compartment.

• Confirm which principal is active: creds me.
• Verify the compartment scope is correct (compartments list).
• Try another compartment or a broader-privileged credential (creds swap).
• Run with -v/--debug to see the underlying service status/code: modules run enum_identity -v.

Region errors / wrong region

Set a workspace default region, or pass one when adding the credential:

configs set current_default_region us-phoenix-1
configs regions list                  # list known regions; current default highlighted

Unknown values for current_default_region are accepted with a warning (this supports private/dedicated regions). Auth modes that can auto-detect region (profile, instance principal via IMDS) will use that when no region is set — see Authentication Reference.

Module skips with "DNS timed out" in certain regions

Some OCI services are not available in every region (e.g. Generative AI is not available in ca-montreal-1). When OCInferno tries to reach a service endpoint that has no DNS record in the configured region, it now times out in ≤ 10 seconds and prints a yellow skip line:

[-] enum_generative_ai.projects: skipped (DNS timed out after 10s for
    'generativeai.ca-montreal-1.oci.oraclecloud.com' — the OCI endpoint may not
    exist in this region.)

This is expected behaviour — the skip is recorded and the run continues. Subsequent compartments in the same region reuse the cached failure result and skip instantly.

If you want to run a specific module against a different region without changing the workspace default, use --regions:

modules run enum_generative_ai --regions us-chicago-1

process_og_node_color_images returns a 409 conflict

A 409 "Conflict: duplicate kind name" means node kinds from a previous push are still registered in BloodHound. Use --reset to clear them and re-push in one step:

modules run process_og_node_color_images \
  --custom-nodes-token-id TOKEN_ID --custom-nodes-token-key TOKEN_KEY --reset

Or wipe without re-pushing (e.g. before switching to a fresh BloodHound instance):

modules run process_og_node_color_images \
  --custom-nodes-token-id TOKEN_ID --custom-nodes-token-key TOKEN_KEY --clear

Auth fails at startup

Map the exact error message to a cause/fix using the Common Auth Errors table. Quick checks:

• OCIDs must start with ocid1. and the fingerprint must be colon-delimited hex.
• For direct api-key mode, all of --user, --fingerprint, --tenancy-id, --region, and a key (--private-key / --private-key-file) are required.
• For session-token, add --tenancy-id if it cannot be extracted from the token.
• Balance your quotes — startup parsing uses shell-style tokenization.

Routing traffic through a proxy (e.g. Burp)

Set a workspace-wide proxy, or override per run:

configs set proxy http://127.0.0.1:8080          # all module runs
modules run enum_identity --proxy http://127.0.0.1:8080   # single run
configs unset proxy                               # remove the default later

Startup credential auth exchanges use a separate --auth-proxy flag (ocinferno --auth-proxy http://127.0.0.1:8080), because some federation flows (notably instance-principal x509 exchange) fall outside the per-module proxy. See Authentication Reference.

Where does output and data live?

• Downloaded artifacts and exports: ./ocinferno_output/<workspace_id>_<workspace_name>/... (override an individual export with --out-dir / --out-file).
• SQLite database (under ocinferno/databases/): one unified file, ocinferno.db, holding workspaces/credentials/user-permissions plus every enumerated resource table (schema from mappings/database_info.json). --db service/--db metadata below both point at this same file — the split is a query-scope convenience, not two separate files.

Query them directly:

data sql --db service "SELECT * FROM identity_policies LIMIT 20"
data sql --db metadata "SELECT * FROM workspaces"

The compartment-tree image (data export treeimage) is empty

The tree image is rendered from the saved compartment hierarchy. Populate it first:

modules run enum_comp
data export treeimage

OpenGraph / BloodHound output is empty or missing IAM data

process_oracle_cloud_hound_data builds the graph from already-saved data, so enumerate first (IAM policies and the compartment tree are the key inputs):

modules run enum_all --comp --get
modules run process_oracle_cloud_hound_data --expand-inherited --reset --out opengraph_output.json

Use --reset to wipe the OpenGraph tables before generating so each run is fresh. For graph semantics see OpenGraph - Node/Edge Tables, OpenGraph - Default Priv Escalation Mode, OpenGraph - IAM Conditionals, and OpenGraph - Inheritance & IncludeAll.

How do I audit collected data for misconfigurations?

Run the saved-data configuration audit engine after enumeration:

modules run process_config_check

See ConfigChecker - Static Config Checks for the full findings catalog.

Where are the module contract and contributor docs?

• Module contract + invariants: Module Development Guide and CLAUDE.md.
• Contributing guidance: CONTRIBUTING.md.