ByteGraph: Bytecode-Level Semantic Graph Constructor

이 프로젝트는 Apache BCEL과 IBM WALA를 결합하여 Java 클래스 파일(.class)로부터 의미 수준의 그래프(CFG/DFG/CDG/DDG)를 추출하는 정적 분석 도구입니다.

1. 핵심 기능 (Key Features)

• 물리적 정보 보존 (BCEL): Apache BCEL을 통해 명령어별 오프셋(Offset), 니모닉(Mnemonic), 피연산자(Operands) 및 실제 16진수 바이트열(Hex) 정보를 추출합니다.
• 의미론적 분석 (WALA): IBM WALA를 활용하여 **데이터 흐름(DFG), 제어 의존성(CDG), 데이터 의존성(DDG)**을 정밀 분석합니다.
• 오프셋 기반 정밀 매핑: WALA의 분석 결과를 BCEL의 바이트코드 오프셋으로 투영(Mapping)하여 정보 손실 없는 통합 모델을 제공합니다.
• 통합 JSON 출력: 분석된 노드와 5가지 엣지 유형(CFG, EX, DFG, CDG, DDG)을 하나의 JSON 파일로 직렬화하여 출력합니다.

2. 환경 설정 (Prerequisites)

• java Runtime: 본 도구는 Java 21 환경에서 구현 및 실행을 권장합니다.
• 빌드 도구: 의존성 관리 및 빌드를 위해 Gradle을 사용합니다.

3. 사용 방법 (Usage)

프로그램 실행 시 분석하고자 하는 .class 파일 경로 또는 패키지 루트 디렉토리를 인자로 전달합니다.

실행 예시 (Windows 환경)

run-bytegraph.bat "<분석 대상 경로>"

실행 예시 (Mac/Linux 환경)

run-bytegraph.sh "<분석 대상 경로>"

분석 옵션

• DFG mode
  • DATA_STACK : 스택 수준의 모든 흐름 포함
  • DATA_SEMANTIC (기본) : 스택 수준의 분석을 수행하되, 의미 없는 (실제로 사용되지 않는) 데이터 흐름 제외
  • DATA_LOCAL : 스택 수준의 흐름 제외
  • WALA_ONLY : 스택 수준의 분석만 아니라, BCEL을 사용한 물리적 분석 모두 제외

• Analyze mode
  • ALL (기본) : CFG, DFG, CDG, DDG, EX 모두 생성
  • FLOW_ONLY : CFG(예외 엣지 포함), DFG만 생성
  • DEPENDENCY_ONLY : CDG, DDG만 생성

4. 출력 데이터 구조 (Output Format)

모든 분석 결과는 out/ 폴더 내에 JSON 형식으로 저장되며, 각 메서드별로 다음과 같은 정보를 포함합니다.

• nodes: 명령어의 물리적 속성을 포함합니다.
  • offset: 바이트코드 오프셋.
  • hex: 16진수로 변환된 원본 바이트열.
  • mnemonic: 명령어 니모닉.
  • operands: 명령어 피연산자 정보.

• edges: 바이트코드 오프셋(src, dst)을 기준으로 한 5가지 연결 정보를 제공합니다.
  • cfg: 명령어 간의 정상적인 제어 실행 흐름.
  • ex: 예외 테이블 기반의 예외 처리 핸들러 흐름.
  • dfg: 데이터의 생성과 소비 경로를 나타내는 데이터 흐름.
  • cdg: 분기 결정에 의한 명령어 실행 제어 의존성.
  • ddg: 힙 메모리 및 변수 간의 정밀한 데이터 의존성.

5. 기술 스택 (Tech Stack)

• Java 21
• Apache BCEL 6.11.0: 저수준 바이트코드 구조 분석 및 물리적 정보 추출.
• IBM WALA 1.6.12: SSA IR 변환 및 고수준 프로그램 의존성(DFG, CDG, DDG) 분석.
• Jackson 2.17.2: 분석 데이터의 JSON 직렬화 및 출력.

6. 현재 한계점 (Known Limitations)

• 전역 데이터 흐름 전파 누락 (Fixed-point Analysis 부재)
  • 현재 DFG는 단일 방향(One-pass)으로 동작하여 선형적인 흐름만 포함합니다.
  • 루프(Loop)나 복잡한 분기 합류 지점에서의 데이터 전파가 정확하지 않습니다.
  • 향후 개선 사항 : 고정점 분석을 추가할 예정입니다.
• 외부 라이브러리 의존성 수동 포함 (Dependency)
  • 분석 대상 클래스가 참조하는 외부 라이브러리(.jar)가 없을 경우, 해당 클래스의 분석이 실패합니다.
  • 향후 개선 사항 : 외부 라이브러리가 없을 경우, 정확도가 떨어지더라도 주어진 정보로 그래프 완성시키게 수정할 예정입니다.
• 물리적-논리적 매핑 정밀도
  • 바이트코드 오프셋(BCEL)과 SSA 인덱스(WALA) 간의 맵핑 정확도는 99%로, 100%가 아닙니다.
  • 컴파일러 최적화에 의해 1:N 매핑의 모호함이 존재할 수 있습니다.
• 메서드 외 분석
  • 현재 프로젝트는 메서드 내에서만 그래프를 추출합니다.
  • 메서드 간 호출관계나 데이터 흐름, 객체 사용 등은 분석에 포함되지 않습니다.

다음은 프로젝트의 목적(모델 학습을 위한 실용적/효율적 그래프 추출)에 부합하지 않는다고 판단되어, 분석 범위에 포함되지 않는 제외 사항입니다.

• CFG 정밀도 (예외 흐름 포함)
  • 바이트코드가 실제 VM에서 실행될 때 발생할 수 있는 모든 (예외적인) 실행 흐름을 표현하지 않습니다.
  • 논리적 수준에서의 실행 흐름을 표현합니다.
• 동적 분석
  • 네이티브 코드(JNI): JVM 외부(C/C++)에서 실행되는 로직은 분석하지 않습니다.
  • 리플렉션(Reflection): 실행 시점에 문자열로 클래스나 메서드를 결정하는 동적 호출은 분석의 범위를 벗어납니다.
  • 멀티스레드 환경 : 여러 개의 스레드가 동시에 실행될 때 발생하는 상호작용(Interleaving)은 고려하지 않습니다.
  • 포인터 분석의 보수적 근사 : WALA는 하나의 참조 변수가 런타임에 가리킬 수 있는 모든 객체 후보를 추적합니다. 특정 변수가 여러 객체와 연결될 가능성이 있을 때, 이를 모두 연결합니다.

위에서 명시한 항목 외에도, 정적 분석의 특성 및 바이트코드의 복잡성에 따라 분석의 정밀도가 부분적으로 저하되거나 특정 실행 경로가 분석 범위에서 제외될 가능성이 존재합니다. 본 프로젝트는 범용적인 코드 패턴 학습을 위한 최적의 그래프 구성을 지향하며, 탐지되지 않은 미세한 로직 유실은 지속적인 엔진 고도화를 통해 개선해 나갈 예정입니다.