업데이트로 돌아가기
New releaseJul 24, 2026

trailmark v0.5.0

소스 코드의 그래프 데이터베이스 표현을 구축하고 쿼리합니다

공유

Trailmark

CI Mutation Testing

Trailmark는 소스 코드를 함수, 타입, 호출 및 기타 관계로 이루어진 그래프로 파싱한 뒤, 이에 대한 구조적 질문을 할 수 있게 해줍니다:

  • 어떤 진입점이 이 함수에 도달할 수 있으며, 어떤 호출 경로를 통해 도달하는가?
  • 두 커밋 사이에 공격 표면에서 무엇이 변경되었는가?
  • 어떤 함수가 이 Solidity 스토리지 변수를 쓰는가?
  • 호출 해석이 어디에서 멈췄기에 도달 가능성 결과가 불완전한가?

지원되는 언어를 tree-sitter를 통해 파싱하고, 그래프를 rustworkx에 저장하며, 명령줄 도구와 Python API를 통해 노출합니다. Trailmark는 보안 검토를 위해 만들어졌습니다: 모든 엣지는 구문에서 직접 나온 것인지 휴리스틱에서 나온 것인지를 기록하며, 해석하지 못한 호출도 그래프에 남습니다.

장기적인 비전은 이 그래프를 뮤테이션 테스팅 및 커버리지 기반 퍼징과 결합하여, 사용자 입력으로부터 도달 가능한 가정과 테스트 커버리지 사이의 격차를 식별하는 것입니다.

기능

  • 코드 그래프. 함수, 메서드, 클래스, 구조체, 트레이트, 컨트랙트, 모듈이 호출, 상속, 포함, 타입 사용으로 연결됩니다. --language auto는 트리 내 지원되는 모든 언어를 하나의 그래프로 병합합니다.
  • 공격 표면. 프레임워크 인식 진입점 탐지(Flask, FastAPI, Spring, ASP.NET Core, actix-web, NestJS, Elysia HTTP 등록, Solidity 가시성 등)를 제공하며, 각각 신뢰 수준과 자산 가치로 태그가 지정됩니다. .trailmark/entrypoints.toml로 탐지를 재정의하거나 확장할 수 있습니다.
  • 진입점 증거. 호출 가능 및 선언적 참조, 실행 가능한 파일 본문, 소스 출처가 있는 미해결 후보를 검사합니다. 참조는 실행과 분리되어 유지됩니다. 명시적 제외와 함께 추가 소스 루트를 선택할 수 있습니다.
  • 도달 가능성. 직접 호출자와 피호출자, 전이적 슬라이스, 진입점에서 대상까지의 경계가 지정된 호출 경로를 제공합니다.
  • 구조적 차이. 두 디렉터리 또는 git ref를 비교하고 추가되거나 제거된 선언, 시그니처 및 타입 변경, 호출 엣지 신뢰도 변경, 진입점을 보고합니다.
  • 다이어그램. Mermaid 호출 그래프, 클래스 계층, 모듈 의존성, 포함 뷰, 복잡도 맵, 진입점-대상 흐름을 제공합니다.
  • 그래프 상의 발견 사항. SARIF 및 weAudit 결과를 가져오고, 자체 주석을 첨부하며, 사전 분석 패스(영향 범위, 권한 경계, 개략적 오염 분석)를 실행하여 결과를 주석 및 명명된 서브그래프로 저장합니다.
  • 가시적 공백. 해결할 수 없는 호출은 사라지는 대신 프록시 노드가 되며, trailmark analyze --resolution이 이를 집계합니다.
  • 예외 증거. exception_events()로 소스 위치가 지정된 throw, rethrow, 핸들러 및 정리 구문을 검사합니다. 알 수 없는 throw 피연산자는 계속 표시됩니다. 프런트엔드 커버리지와 이 구문 증거의 한계는 그래프 모델을 참조하세요.
  • Trailmark가 볼 수 없는 링크. RPC, FFI, 서브프로세스 엣지를 .trailmark/links.toml에 선언하거나, 바이너리 분석 도구가 생성한 호출 그래프를 가져옵니다.
  • 컴파일된 바이너리 증거. 링크된 ELF, Mach-O, PE 이미지를 명시적으로 검사하고, 소스 함수와 라인을 컴파일된 범위에 연결하며, 바이너리 호출과 추론된 테일 전송을 복구하고, 15개 아키텍처/모드 케이스에 걸쳐 경계가 지정된 디스어셈블리를 쿼리합니다. 스트립된 코드 매핑, 유니버설 슬라이스, 검증된 로컬 디버그 컴패니언, 폴딩된 별칭, 명명된 임포트 항목을 포함합니다. 선택적 trailmark[binary] 추가 기능과 호스트 도구 요구 사항은 바이너리 증거를 참조하세요.
  • Solidity 스토리지 접근. 함수와 함수가 접근하는 컨트랙트 상태 변수 간의 reads 및 writes 엣지.

설치

uv tool install trailmark        # the CLI
uv add trailmark                 # the library, in a uv-managed project

Python ≥ 3.12가 필요합니다. CI는 Python 3.12부터 3.15까지 테스트합니다. Nix를 사용하면 nix run github:trailofbits/trailmark로 CLI를 직접 실행할 수 있습니다.

이 README와 가이드는 main 브랜치를 따릅니다. 변경 로그에는 각 배포 릴리스에 포함된 내용이 나열되어 있으며, CLI 및 Python API 가이드에는 각 최신 기능을 추가한 버전이 명시되어 있습니다.

대부분의 문법은 처음 사용할 때 다운로드되어 캐시됩니다. 번들 문법은 처음 사용할 때 컴파일되며, 이를 위해서는 C 컴파일러가 필요합니다. 오프라인 머신, TLS 검사 프록시, 체크아웃에서 빌드하는 방법은 설치를 참조하세요.

스킬 통합자: 스키마, 아이덴티티, 상태, 도달 가능성 검사에 대해서는 v0.7 호환성을 참조하세요.

빠른 시작

# Node and edge counts for a Python project (Python is the default language)
trailmark analyze --summary path/to/project

# The same summary as JSON, including source-file counts per language (v0.7+)
trailmark analyze --summary --json --language auto path/to/project

# Full JSON graph of every supported language in the tree
trailmark analyze --language auto path/to/project > graph.json

# Detected entrypoints with trust level and asset value
trailmark entrypoints --language auto path/to/project

# How the attack surface changed between two git refs
trailmark diff --repo . main HEAD

# Mermaid call graph around one function
trailmark diagram -t path/to/project -T call-graph -f handle_request

# How many call sites could not be resolved, grouped by callee name
trailmark analyze --language rust --resolution path/to/project

디렉터리 분석은 존재하지 않는 루트와 일치하는 소스 파일이 없는 경우를 거부합니다. 요약에는 선택된 언어와 검사한 파일 수가 포함됩니다. 의도적으로 빈 입력을 사용하려면 --allow-empty를 사용하세요. 그래프 JSON에는 내보낸 Trailmark 버전과 내보내기 스키마 버전(v0.7+)이 포함됩니다. 동일한 Trailmark 버전과 언어로 생성된 스냅샷을 비교하세요.

Python에서의 동일한 질문:

from trailmark.query.api import QueryEngine

engine = QueryEngine.from_directory("path/to/project", language="auto")

engine.attack_surface()                    # entrypoints and their trust levels
engine.callers_of("verify_signature")      # direct callers
engine.ancestors_of("verify_signature")    # everything that can reach it
engine.entrypoint_paths_to("verify_signature")
engine.complexity_hotspots(10)             # cyclomatic complexity >= 10

이름은 단순형(verify_signature), 정규화형(Auth.verify), 또는 전체 노드 ID(auth:Auth.verify)일 수 있습니다. 쿼리 결과는 JSON으로 직접 직렬화되는 일반 dict와 list입니다.

작동 방식

flowchart LR
    A["Source files"] --> B["tree-sitter parsers"]
    B --> C["CodeGraph"]
    C --> D["GraphStore (rustworkx)"]
    D --> E["QueryEngine"]
    E --> F["CLI / Python API"]

    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. 파싱. 각 언어별 파서가 디렉터리를 순회하며 노드 (함수, 타입, 모듈), 엣지(호출, 상속, 포함 관계 등), 그리고 메타데이터(매개변수, 반환 타입, 분기, 순환 복잡도, docstring, 발생 예외)를 추출합니다. 이어서 링킹 단계가 파일 간 호출을 해석하고, 타입을 해당 선언에 연결하며, .trailmark/links.toml을 적용합니다.
  2. 인덱싱. GraphStore는 빠른 순회를 위해 그래프를 rustworkx 방향 그래프에 로드합니다. QueryEngine.from_directory()는 진입점 탐지도 실행합니다.
  3. 쿼리. QueryEngine은 이름을 노드 ID로 해석하고, 순회를 실행하며, JSON 직렬화 가능한 결과를 반환합니다.

예제

다음 app.py가 주어졌을 때:

class Auth:
    def verify(self, token):
        return self._check_sig(token)

    def _check_sig(self, token): ...


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


def process(req): ...
def deny(): ...

Trailmark는 이 그래프를 생성합니다(모듈 포함 관계 엣지는 생략됨):

graph TD
    HR["app:handle_request"] -->|calls| A["app:Auth"]
    HR -->|calls| PV["proxy.unresolved:auth.verify"]
    HR -->|calls| P["app:process"]
    HR -->|calls| D["app:deny"]
    AV["app:Auth.verify"] -->|calls| CS["app:Auth._check_sig"]
    A -->|contains| AV
    A -->|contains| CS

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

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

self._check_sig(...)는 self가 둘러싸는 클래스를 가리키므로 해석됩니다. auth.verify(...)는 Trailmark가 지역 변수 auth가 Auth를 보유한다고 추론하지 않기 때문에 해석되지 않습니다. 이 호출은 삭제되지 않고 프록시 노드로 유지됩니다. 그 결과, engine.ancestors_of("Auth._check_sig")는 app:Auth.verify만 반환하고, engine.unresolved_calls("handle_request")는 경로가 유실된 정확한 호출 지점을 보여줍니다. 모든 노드 종류, 엣지 종류, ID 규칙은 Graph model을, 프록시 작업 방법은 Call resolution을 참조하세요.

지원 언어

카테고리