Root Cause Analysis Tool (RCA) — CLI Chatbot for Software Crash Analysis

Analyze software crash stack traces with AI. A command-line root cause analysis (RCA) tool that uses OpenAI's API to interpret crash stack traces and identify the root cause of software failures. Built with TypeScript and Node.js.

---

Quick links

• What is this? · Install & run · How to use · Author & contact

---

What is this tool?

This is a root cause analysis (RCA) chatbot that:

• Reads stack trace files from software crashes (e.g. from fuzzing or debugging).
• Sends them to OpenAI's API (GPT) for analysis.
• Returns a plain-language explanation of the likely root cause of the crash.

It was developed as part of the SE6005 Capstone Project for the Master of Science in Cyber Security (MSCS) at Nanyang Technological University (NTU), Singapore, to explore whether an LLM-based RCA tool can be a practical alternative to traditional RCA methods—with a focus on accuracy and ease of understanding.

Keywords: root cause analysis, RCA, software crash analysis, stack trace, LLM, large language model, OpenAI, ChatGPT, security testing, software testing, fuzzing, CVE, CLI tool, TypeScript, Node.js.

---

Features

• CLI-based: Run locally from the terminal; no web UI required.
• Batch analysis: Analyze multiple stack trace files in one session (subject to token limits).
• Interactive follow-up: Ask follow-up questions or request re-analysis (readCrashes).
• Session logging: Prompts and responses are saved in sessions/ for later review.

---

Prerequisites

Node.js

You need Node.js to run the tool. Developed with Node v20.10.0 (macOS Sonoma 14.3.1).

node -v

TypeScript

TypeScript is a project dependency and is installed with npm i. Developed with TypeScript 5.3.3.

tsc -v

---

Setup

1. Get an OpenAI API key
   Create a key at OpenAI API keys.

2. Create a .env file in the project root:

   API_KEY=<YOUR_API_KEY_HERE>
   

   Replace <YOUR_API_KEY_HERE> with your actual API key.

3. Install dependencies:

   npm i

4. Run the chatbot:

   npm run ce

   This cleans dist/, compiles TypeScript from src/ to dist/, then runs node dist/index.js.

   Manual compile and run:

   tsc
   node dist/index.js

   To run without recompiling (after a previous build):

   node dist/index.js

Project structure (reference)

rca-tool/
├── crashes/       # Put stack trace files here for analysis
├── dist/          # Compiled JavaScript (after tsc)
├── node_modules/
├── samples/       # Sample stack traces from CVE fuzzing
├── sessions/      # JSON logs of past sessions
├── src/           # TypeScript source
│   ├── components/
│   ├── config/
│   └── index.ts
├── tests/
├── .env           # You create this with API_KEY=...
├── package.json
├── tsconfig.json
└── README.md

---

Usage

1. Add stack traces
   Place text files containing stack trace output in the crashes/ folder. Example content:

   ==11852==ERROR: AddressSanitizer: heap-buffer-overflow on address 0x602000003033 at pc 0x556321736838 bp 0x7ffe4d212270 sp 0x7ffe4d212260
   WRITE of size 1 at 0x602000003033 thread T0
       #0 0x556321736837 in quote_for_pmake asm/nasm.c:856
       #1 0x556321736837 in quote_for_pmake asm/nasm.c:784
       ...
   

2. Choose how many files to analyze
   When you run the tool, you’ll be asked how many stack trace files to read. The effective limit is the smaller of:

   • The number you enter, and
   • The number of files in crashes/
     Token usage is capped (e.g. 10,000 tokens); total size of selected files must stay within that. You can estimate tokens with OpenAI’s tokenizer. Files are read in alphabetical order by filename.

3. After the analysis you can:

   • Follow up: Type a normal message to ask for clarification or more detail.
   • Re-analyze: Type readCrashes (no extra words).
   • Quit: Type quit or exit.

Notes:

• Ending the session with Ctrl+C is not recommended (though it typically won’t corrupt files).
• The number of stack traces you can analyze in one go depends on file content and the token limit.

---

tsconfig.json

The repo includes a tsconfig.json for TypeScript. If you need to recreate it, run tsc --init and align with the options used in the project (e.g. target: "es2016", module: "commonjs", rootDir: "./src", outDir: "./dist", sourceMap: true, strict type-checking). See the full example in the original documentation or in the repository.

---

Stack trace sample pool (testing)

Stack traces from the following CVEs were used when testing this tool:

CVE	Command (example)	Status	# Stack traces
CVE-2020-7060	./php_fuzz inputs/crashes/id%3A000000	Control	51
CVE-2023-31722	./nasm_fuzz -f elf64 inputs/crashes/id%3A000000	Control	69
CVE-2021-20284	./nm-new_fuzz --synthetic inputs/crashes/id%3A000000	Variable	109
CVE-2022-44370	./nasm_fuzz -M inputs/crashes/id%3A000000	Variable	210

Status: Control = equal stack trace outputs; Variable = varying stack trace outputs. Each trace was saved as a .txt file (e.g. ./php_fuzz inputs/crashes/id%3A000050 &> 50.txt).

---

Disclaimer

"ChatGPT can make mistakes. Consider checking important information." — OpenAI

This tool is for learning and education. Use it as one input among others; consult documentation, other tools, or experts when the result matters. You can re-run analysis by typing readCrashes when the chatbot prompts for input.

---

Author & contact

KuchikiRenji

• GitHub: github.com/KuchikiRenji
• Email: KuchikiRenji@outlook.com
• Discord: kuchiki_renji

---

License

MIT. See LICENSE in the repository.