classDef src fill:#007bff26,stroke:#007bff,color:#007bff
classDef parse fill:#28a74526,stroke:#28a745,color:#28a745
classDef data fill:#6f42c126,stroke:#6f42c1,color:#6f42c1
classDef query fill:#ffc10726,stroke:#e6a817,color:#e6a817

class A src
class B parse
class C,D data
class E,F query

### 1. 파싱

언어별 파서가 디렉터리를 탐색하고 각 파일을 tree-sitter AST로 파싱하여 다음을 추출합니다:

- **노드** — 함수, 메서드, 클래스, 구조체, 인터페이스, 트레이트, 열거형, 모듈, 네임스페이스
- **에지** — 호출, 상속, 구현, 포함, 임포트
- **메타데이터** — 타입 어노테이션, 순환 복잡도, 분기, 독스트링, 예외 타입

### 지원 언어

| 언어 | 확장자 | 주요 구조 |
| --- | --- | --- |
| Python | `.py` | 함수, 클래스, 메서드 |
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | 함수, 클래스, 화살표 함수 |
| TypeScript | `.ts`, `.tsx` | 함수, 클래스, 인터페이스, 열거형 |
| PHP | `.php` | 함수, 클래스, 인터페이스, 트레이트 |
| Ruby | `.rb` | 메서드, 클래스, 모듈 |
| C | `.c`, `.h` | 함수, 구조체, 열거형 |
| C++ | `.cpp`, `.hpp`, `.cc`, `.hh`, `.cxx`, `.hxx` | 함수, 클래스, 구조체, 네임스페이스 |
| C# | `.cs` | 메서드, 클래스, 인터페이스, 구조체, 열거형, 네임스페이스 |
| Java | `.java` | 메서드, 클래스, 인터페이스, 열거형 |
| Go | `.go` | 함수, 메서드, 구조체, 인터페이스 |
| Rust | `.rs` | 함수, 구조체, 트레이트, 열거형, impl 블록 |
| Solidity | `.sol` | 컨트랙트, 인터페이스, 라이브러리, 함수, 모디파이어, 구조체, 열거형 |
| Cairo | `.cairo` | 함수, 트레이트, 구조체, 열거형, impl 블록, StarkNet 컨트랙트 |
| Circom | `.circom` | 템플릿, 함수, 시그널, 컴포넌트 |
| Haskell | `.hs` | 함수, 데이터 타입, 타입 클래스, 인스턴스 |
| Erlang | `.erl` | 함수, 레코드, 비헤이비어, 모듈 |
| Miden Assembly | `.masm` | 프로시저, 진입점, 상수, 호출 |
| Swift | `.swift` | 함수, 클래스, 구조체, 열거형, 프로토콜, 익스텐션 |
| Objective-C | `.m`, `.mm`, `.h` | C 함수, 클래스, 메서드 (셀렉터 기반 명명) |
| Kotlin | `.kt`, `.kts` | 함수, 클래스, 인터페이스, 데이터 클래스, 객체, 메서드 |
| Dart | `.dart` | 함수, 클래스, 추상 클래스, 메서드, 생성자 |
| Move | `.move` | 모듈, 함수, 임포트, 직접 호출 |
| Tact | `.tact` | 컨트랙트, 구조체, 리시버, 함수 |
| Func | `.fc`, `.func` | 함수, 포함, 직접 호출 |
| Sway | `.sw` | ABI 인터페이스, 구조체, impl 메서드, 함수 |
| Rego | `.rego` | 패키지, 임포트, 정책 규칙, 규칙 호출 |
| Proto | `.proto` | 서비스, RPC, 메시지, 필드, 열거형 |
| Thrift | `.thrift` | 서비스, 함수, 구조체, 필드, 열거형 |
| GraphQL | `.graphql`, `.gql` | 객체 타입, 루트 연산, 필드, 열거형 |
| SQL | `.sql` | 스키마, 테이블, 뷰, 함수, 프로시저 |```mermaid
flowchart TD
    subgraph "Per-File Parsing"
        F["Source file"] --> TS["tree-sitter AST"]
        TS --> EX["Extract nodes"]
        TS --> EC["Extract call edges"]
        TS --> EB["Count branches"]
        TS --> ET["Resolve types"]
    end

    EX --> CG["CodeGraph"]
    EC --> CG
    EB --> CG
    ET --> CG

    classDef src fill:#007bff26,stroke:#007bff,color:#007bff
    classDef parse fill:#28a74526,stroke:#28a745,color:#28a745
    classDef extract fill:#ffc10726,stroke:#e6a817,color:#e6a817
    classDef data fill:#6f42c126,stroke:#6f42c1,color:#6f42c1

    class F src
    class TS parse
    class EX,EC,EB,ET extract
    class CG data

class CodeUnit {
    id: str
    name: str
    kind: NodeKind
    location: SourceLocation
    parameters: tuple[Parameter]
    return_type: TypeRef
    exception_types: tuple[TypeRef]
    cyclomatic_complexity: int
    branches: tuple[BranchInfo]
    docstring: str
}

class CodeEdge {
    source_id: str
    target_id: str
    kind: EdgeKind
    confidence: EdgeConfidence
}

class Annotation {
    kind: AnnotationKind
    description: str
    source: str
}

class EntrypointTag {
    kind: EntrypointKind
    trust_level: TrustLevel
    description: str
    asset_value: AssetValue
}

CodeGraph "1" *-- "*" CodeUnit
CodeGraph "1" *-- "*" CodeEdge
CodeGraph "1" *-- "*" Annotation
CodeGraph "1" *-- "*" EntrypointTag

**노드 종류:** `function`, `method`, `class`, `module`, `struct`, `interface`, `trait`, `enum`, `namespace`, `contract`, `library`, `template`, `proxy`

**노드 출처:** `source`, `proxy`, `binary`, `synthetic`

**엣지 종류:** `calls`, `inherits`, `implements`, `contains`, `imports`, `resolves_to`, `type_uses`, `specializes`, `corresponds_to`

**엣지 신뢰도:** `certain`, `inferred`, `uncertain`

미해결 호출은 `proxy.unresolved:<raw-symbol>`과 같은 프록시 노드로 구체화되어, 트래버설 결과는 소스 분석이 해석을 잃어버린 위치를 자동으로 해당 엣지를 삭제하는 대신 보여줄 수 있습니다. 바이너리 분석은 외부 JSON 호출 그래프의 가져오기를 지원합니다. Trailmark는 스스로 실행 파일을 디스어셈블하지 않습니다.

### 그래프 예시

다음 Python 코드를 고려하세요:```python
class Auth:
    def verify(self, token: str) -> bool:
        return self._check_sig(token)

    def _check_sig(self, token: str) -> bool:
        ...

def handle_request(req: Request) -> Response:
    auth = Auth()
    if auth.verify(req.token):
        return process(req)
    return deny()

classDef fn fill:#007bff26,stroke:#007bff,color:#007bff
classDef cls fill:#6f42c126,stroke:#6f42c1,color:#6f42c1

class HR,P,D fn
class A,AV,CS cls

## 설치

아래 예제는 현재 개발 브랜치를 추적합니다. 최신
출시 패키지는 PyPI에서 설치하세요. 정확한 기능 세트를 사용하려면
여기에 설명된 대로 체크아웃에서 설치하고 `uv run`을 통해 명령을 실행하세요.```bash
# Latest published release
uv pip install trailmark

# Current checkout / development branch
uv sync --all-groups

### 엔트리포인트 탐지

Trailmark는 `graph.entrypoints`를 자동으로 채워 `attack_surface()`, 오염 전파, 권한 경계 교차가 작업할 데이터를 갖도록 합니다. 탐지는 네 개의 계층에서 실행되며, 각 계층은 이전 계층을 재정의합니다:

1. **일반적인 `main` 휴리스틱.** 모든 언어에서 `main`이라는 이름의 함수. `user_input` / `trusted_internal` / `low` 태그가 지정됩니다.
2. **프레임워크 인식 스캔.** 언어별 데코레이터, 속성 및 가시성 패턴 — 아래 표를 참조하세요.
3. **`pyproject.toml [project.scripts]`.** 명시적 CLI 대상은 업그레이드된 신뢰/자산 분류를 받습니다.
4. **저장소 로컬 재정의 파일.** `.trailmark/entrypoints.toml`에 수동으로 선별된 엔트리포인트가 항상 우선합니다.

프레임워크 지원범위:

| 언어 | 탐지된 프레임워크 |
| --- | --- |
| Python | Flask, FastAPI, aiohttp, Click, Typer, Celery |
| JavaScript / TypeScript | NestJS, Next.js (App Router + Pages API), AWS Lambda |
| Java | Spring MVC / WebFlux, JAX-RS, Kafka listeners, servlets |
| C# | ASP.NET Core, Azure Functions |
| PHP | Symfony `#[Route]` attributes + 레거시 어노테이션 |
| Rust | actix-web, rocket, FFI exports (`#[no_mangle]`, `pub extern "C"`), async-main 속성 |
| Solidity | `external` / `public` 가시성 |
| Cairo / StarkNet | `#[external]`, `#[view]`, `#[l1_handler]`, `#[constructor]` |
| Circom | `component main` 선언 |
| Miden Assembly | `export.<name>` 지시문 |
| Haskell | 최상위 `main ::` / `main =` |
| Erlang | `-export([...])`에 나열된 함수 |
| Swift | `@main` 앱 속성 |
| Objective-C | `UIApplicationDelegate` 수명 주기 선택자 (예: `application:openURL:options:`) |
| Kotlin | Spring MVC / WebFlux 어노테이션 (Java와 공유), Android 구성 요소 수명 주기 메서드 (`onCreate`, `onReceive`, `onBind`, ...) |
| Dart | `@pragma('vm:entry-point')` 네이티브 호출 가능 표시자 |
| Go | `http.HandleFunc` / `http.Handle` 표준 라이브러리 등록, gin/chi/echo-style `<router>.GET/POST/...` 핸들러 등록 |
| Ruby | Rails 컨트롤러 액션 (`ApplicationController` / `ActionController::*` 상속 클래스), Sidekiq worker `perform` 메서드 |
| C / C++ | `extern "C"` 링키지, `__attribute__((visibility("default")))`, `__declspec(dllexport)` |

휴리스틱이 놓치는 것은 프로젝트 루트의 `.trailmark/entrypoints.toml`에 엔트리포인트를 명시적으로 선언하세요. 이 파일은 단일 노드와 규칙 기반 항목을 모두 지원합니다:```toml
# Single-node entry
[[entrypoint]]
node = "my_module:handle_request"  # node id, or "module.path:function"
kind = "api"                       # user_input | api | database | file_system | third_party
trust = "untrusted_external"       # untrusted_external | semi_trusted_external | trusted_internal
asset_value = "high"               # high | medium | low
description = "HTTP POST /auth"

# Rule: every PHP script under public_html/ is a web-exposed entrypoint.
[[entrypoint]]
file_glob = "public_html/**/*.php"
kind = "user_input"
trust = "untrusted_external"
asset_value = "high"
description = "Web-exposed PHP script"

# Rule: any function that takes a PSR-7 request object.
[[entrypoint]]
param_type = "ServerRequestInterface"
kind = "api"
trust = "untrusted_external"
asset_value = "high"
description = "PSR-7 HTTP handler"

# Rule: functions named `handle_*`.
[[entrypoint]]
name_regex = "^handle_"
kind = "api"
trust = "untrusted_external"

# Rule: conditions compose with AND — web.py files AND name starts with handle_.
[[entrypoint]]
file_glob = "public/*.py"
name_regex = "^handle_"
kind = "api"
trust = "untrusted_external"

참조는 정확한 노드 ID 또는 고유한 이름/접미사일 수 있습니다. 모호한 참조, 알 수 없는 내부 엔드포인트, 잘못된 열거형 값, 잘못된 형식의 TOML은 `ValueError`를 발생시킵니다. `external = true`로 설정하면 확인되지 않은 엔드포인트를 명시적으로 허용하고 프록시 노드를 생성합니다. 이 파일은 안정적인 공개 구성 인터페이스입니다.

### 분석 제한 사항

- `entrypoint_paths_to()`는 호출 그래프 도달 가능성을 보고하며, 공격자가 제어하는 데이터 흐름은 보고하지 않습니다. 사전 분석 오염 결과를 대략적인 별도 신호로 사용하십시오. Trailmark는 아직 프로시저 간 오염 분석을 수행하지 않습니다.
- TypeScript는 직접 호출과 `new ConcreteClass()`로 할당된 직관적인 수신자를 해석합니다. 매니페스트, 계산된 속성 이름, 의존성 주입 컨테이너 및 기타 동적 메커니즘을 통한 인터페이스 디스패치는 최선의 노력으로 처리됩니다.
- SQL 지원은 PostgreSQL 중심이며 스키마, 테이블, 뷰, 함수, 프로시저, 루틴/뷰 의존성을 추출합니다. 완전한 SQL 방언 유효성 검사기나 쿼리 의미 분석기가 아닙니다.

### 프로그래밍 API```python
from trailmark.parse import parse_directory, parse_file
from trailmark.query.api import QueryEngine

# Parse-only API: get the raw CodeGraph without building GraphStore/QueryEngine.
graph = parse_file("path/to/file.py")
graph = parse_directory("path/to/project", language="auto")

# Single-language (default) or auto-detect + merge across all languages
engine = QueryEngine.from_directory("path/to/project")
engine = QueryEngine.from_directory("path/to/project", language="auto")
engine = QueryEngine.from_directory("path/to/project", language="python,rust")

# Direct neighbors
engine.callers_of("handle_request")
engine.callees_of("handle_request")

# Transitive slicing — who could reach this sink, or what could it reach?
engine.ancestors_of("Auth._check_sig")
engine.reachable_from("handle_request")

# Attack-surface paths from any detected entrypoint
engine.entrypoint_paths_to("Auth._check_sig")

# All call paths between two nodes
engine.paths_between("handle_request", "Auth._check_sig")

# Functions with cyclomatic complexity >= 10
engine.complexity_hotspots(10)

# What functions can raise a given exception? (uses parser-detected
# exception_types; no runtime tracing required)
engine.functions_that_raise("PermissionError")

# Add and query semantic annotations
from trailmark.models.annotations import AnnotationKind

engine.annotate(
    "handle_request",
    AnnotationKind.ASSUMPTION,
    "Caller has already authenticated the session token",
    source="llm",
)
engine.annotations_of("handle_request")
engine.nodes_with_annotation(AnnotationKind.FINDING)

# Diff against an earlier snapshot of the same codebase
before = QueryEngine.from_directory("before/")
diff = engine.diff_against(before)
# diff contains: summary_delta, nodes {added/removed/modified},
# edges {added/removed}, entrypoints {added/removed/modified}

# Run the built-in audit-oriented preanalysis passes
engine.preanalysis()
engine.findings()
engine.subgraph_names()

# Programmatic augmentation hooks for external tooling
engine.augment_sarif("results.sarif")
engine.augment_weaudit("findings.json")

## 라이선스

Apache-2.0