Quipu

YARA 규칙을 작성, 검증, 컴파일, 테스트하기 위한 데스크톱 워크벤치입니다.

Quipu(발음은 "KEE-poo")는 프로젝트 탐색기, YARA를 인식하는 편집기, YARA-X 컴파일러, 그리고 집중적인 스캔 결과를 하나의 로컬 애플리케이션에 담았습니다. YARA-X와 그 언어 서버를 모두 내장하고 있어 별도의 YARA 설치가 필요하지 않습니다.

[!IMPORTANT] Quipu는 MVP 단계입니다. 빌드는 Linux 및 Windows x86-64를 대상으로 합니다. Windows 데스크톱 검증은 Windows 11 24H2를 대상으로 하며, 검증 기록을 참고하세요. 실험적 macOS 빌드는 CI 커버리지와 사용자 확인 빌드 검증을 갖추고 있습니다. 검증 기록을 참고하세요.

기능

• .yar 및 .yara 파일 폴더를 워크스페이스로 열거나, 임시 규칙으로 시작할 수 있습니다.
• 추론되거나 구성된 진입점, 중첩된 include, 외부 include, 프로젝트 문제를 탐색합니다.
• Monaco 구문 강조, 자동 완성, 호버 문서, 실시간 YARA-X 진단 기능으로 편집합니다.
• 전체 워크스페이스를 컴파일한 다음, 입력한 텍스트나 선택한 파일을 스캔합니다.
• 일치하는 규칙, 패턴, 오프셋, 바이트 길이, 그리고 강조 표시된 바이트를 헥스 뷰어에서 확인합니다.
• 진단 및 일치 항목에서 해당 소스 정의로 바로 이동합니다.
• 변경되지 않은 컴파일된 규칙 집합을 제한된 로컬 캐시에서 복원합니다.
• 애플리케이션에 포함된 작고 독립적인 예제 프로젝트 세트로 작업합니다.

규칙과 스캔 대상은 로컬에서 처리됩니다. Quipu는 그 내용을 원격 서비스로 전송하지 않습니다.

Linux에 설치

Linux x86-64 패키지는 GitHub Releases 페이지에 게시됩니다:

패키지	적합한 용도	설치 또는 실행
AppImage	지원되는 배포판에서의 휴대용 사용	chmod +x Quipu_*.AppImage && ./Quipu_*.AppImage
.deb	Ubuntu 22.04+ 및 Debian 12+	sudo apt install ./Quipu_*.deb
.rpm	최신 Fedora 릴리스	sudo dnf install ./Quipu-*.rpm

.deb 및 .rpm 패키지는 시스템 WebKitGTK 런타임을 사용합니다. 사용 중인 배포판이 해당 의존성을 충족하지 못하는 경우 AppImage를 사용하세요.

개발 패키지는 성공한 CI 실행의 quipu-linux-x86_64 아티팩트로 제공됩니다. CI와 Release는 패키지 검증 및 네이티브 메뉴 스모크 테스트를 포함한 동일한 Linux 워크플로를 호출합니다. 통합된 SHA256SUMS 파일은 개별 CI 아티팩트가 아니라 Release에서 제공됩니다.

Quipu 패키지는 현재 서명되지 않습니다. 각 릴리스에는 SHA256SUMS 파일이 포함되며, 패키지 옆에 내려받아 다음 명령으로 내려받은 파일을 검증하세요:

sha256sum --ignore-missing --check SHA256SUMS

체크섬은 우발적인 손상을 감지하지만 인증된 서명은 아닙니다.

Windows에 설치

Windows x86-64 패키지(v0.3.0 이상)의 경우 GitHub Releases에서 설치 프로그램을 다운로드하세요. 개발 빌드는 성공한 CI 실행의 quipu-windows-x86_64 및 quipu-windows-offline-x86_64 아티팩트로도 제공됩니다.

• 현재 사용자 설치에는 NSIS .exe 설치 프로그램을 사용하세요.
• MSI .msi 설치 프로그램도 제공됩니다.
• 에어갭 시스템의 경우 -offline.exe 또는 -offline.msi 설치 프로그램(quipu-windows-offline-x86_64 CI 아티팩트)을 선택하세요. 이 더 큰 패키지에는 전체 Microsoft Edge WebView2 런타임 설치 프로그램이 포함되어 있어 인터넷 접속 없이 설치할 수 있습니다.
• 표준 설치 프로그램은 런타임이 없을 때 WebView2를 다운로드하므로 설치에 인터넷 접속이 필요할 수 있습니다.

설치 프로그램은 서명되지 않았으므로 Windows에서 알 수 없는 게시자 또는 SmartScreen 경고가 표시될 수 있습니다. 계속하기 전에 다운로드가 이 저장소의 릴리스 또는 워크플로에서 이루어졌는지 확인하세요.

릴리스 패키지에는 통합 SHA256SUMS 파일이 포함되어 있습니다. PowerShell에서 다운로드한 설치 프로그램의 해시를 계산하세요(예제 파일명을 바꾸세요):

Get-FileHash -Algorithm SHA256 .\Quipu_VERSION_x64-setup.exe
Get-Content .\SHA256SUMS

해당 정확한 파일명의 항목과 해시를 비교하되, 대소문자는 무시합니다. 개별 CI 아티팩트에는 통합 릴리스 체크섬 파일이 포함되지 않습니다.

재시작 후 컴파일된 규칙셋이 사라졌다면, 번들 가이드의 Windows Defender 문제 해결을 확인하세요. 격리 여부를 확인하는 방법과 필요한 경우 캐시 디렉터리만 제외하는 방법이 설명되어 있습니다.

실험적 macOS 빌드

CI 워크플로는 macOS 15 이상을 대상으로 Apple Silicon 및 Intel용 임시 서명(ad-hoc signed) DMG를 빌드합니다. 빌드에 Apple Developer 멤버십은 필요하지 않지만, 공증(notarization)되지 않으므로 실행하려면 Gatekeeper 우회가 필요할 수 있습니다. CI 아티팩트, 빌드 지침 및 현재 검증 상태는 macOS 개발을 참조하세요.

빠른 시작

1. Quipu를 시작하고 File → Open Example… → Basic text match를 선택합니다.
2. 편집기에서 text_indicators.yar를 살펴봅니다.
3. Rules → Compile Workspace를 선택하거나 Ctrl+Shift+B를 누릅니다.
4. Rules → Scan Target을 선택하거나 Ctrl+Shift+Enter를 눌러 준비된 대상을 스캔합니다.
5. 매치를 확장하고 선택하여 강조 표시된 바이트를 검사합니다.

전체 가이드는 Help → Documentation 아래에 Quipu와 함께 번들로 제공됩니다. 소스는 documentation/content에서도 확인할 수 있습니다.

워크스페이스와 quipu.toml

구성 없이도 Quipu는 규칙 파일을 재귀적으로 탐색하고, 다른 파일에 포함되지 않은 각 파일에서 진입점(entrypoint)을 추론합니다. 명시적 진입점, 포함 디렉터리 또는 제외 항목이 필요하면 워크스페이스 루트에 quipu.toml을 추가하세요:

schema = 1
entrypoints = ["main.yar"]
include_dirs = ["rules", "../shared-rules"]
exclude = ["fixtures/**", "vendor/legacy/**"]

프로젝트 모델과 매니페스트 참조의 전체 내용은 워크스페이스와 프로젝트를 참고하세요.

소스에서 빌드

모든 플랫폼에 필요한 항목:

• Rust 1.93 이상
• Node.js 22.12 이상
• Zola 0.23.6
• Git

Windows의 경우 MSVC 빌드 도구, Windows SDK, WebView2 런타임, PowerShell 빌드 명령에 대해서는 Windows 개발을 따르세요.

실험적인 macOS 빌드의 경우 macOS 개발을 따르세요.

Linux의 경우 Tauri와 WebKitGTK에 필요한 네이티브 라이브러리도 필요합니다.

Debian 또는 Ubuntu에서는 다음 명령으로 네이티브 의존성을 설치하세요:

sudo apt update
sudo apt install -y \
  build-essential \
  curl \
  file \
  libayatana-appindicator3-dev \
  libgtk-3-dev \
  librsvg2-dev \
  libssl-dev \
  libwebkit2gtk-4.1-dev \
  patchelf \
  rpm \
  wget

그런 다음 세 가지 Linux 패키지 형식을 모두 빌드합니다:

git clone https://github.com/corelight/quipu.git
cd quipu/app
npm ci
npm run tauri -- build --bundles appimage,deb,rpm

아티팩트는 app/src-tauri/target/release/bundle/ 아래에 작성됩니다. 첫 빌드는 Cargo가 YARA-X와 그 의존성을 소스에서 컴파일하기 때문에 시간이 걸릴 수 있습니다.

Windows 빌드 설정, 설치 프로그램 동작, 파일 시스템 제한 사항은 Windows development에 설명되어 있습니다.

개발 및 테스트

의존성을 설치하고 개발 애플리케이션을 시작합니다:

cd app
npm ci
npm run tauri -- dev

프론트엔드 단위 테스트, 프로덕션 프론트엔드 빌드, Rust 테스트를 다음 명령으로 실행합니다:

cd app
npm test
npm run build

cd src-tauri
cargo test --locked

네이티브 메뉴 인수 테스트에는 추가적인 Linux 디스플레이 서버 요구 사항이 있습니다. 설정 및 사용법은 test/README.md를 참조하세요.

아키텍처

Quipu는 바닐라 TypeScript 프런트엔드와 Rust 백엔드로 구성된 Tauri 애플리케이션입니다:

• Vite는 프런트엔드와 Monaco 편집기를 애플리케이션 웹뷰로 번들링합니다.
• Tauri IPC는 UI를 Rust의 워크스페이스, 파일시스템, 컴파일, 캐시, 스캐닝 서비스에 연결합니다.
• YARA-X 컴파일러와 언어 서버는 프로세스 내에서 실행됩니다.
• Zola는 앱에 내장되는 오프라인 문서 사이트를 빌드합니다.

app/src/           TypeScript frontend
app/src-tauri/     Rust backend and desktop packaging
documentation/    Source for the bundled offline guide
examples/          Projects bundled with the application
test/ui/           Native-menu acceptance test harness

애플리케이션 버전은 app/package.json에 정의되어 있으며, Tauri는 패키지 이름을 지정하고 실행 중인 버전을 보고할 때 해당 값을 읽습니다.

현재 제한 사항

• 릴리스 패키지는 Linux 및 Windows x86-64를 대상으로 합니다. macOS Apple Silicon 및 Intel 빌드는 실험적인 CI 아티팩트로 남아 있습니다. 자세한 내용은 macOS 검증 기록을 참조하십시오.
• Quipu는 디렉터리나 배치가 아닌, 선택한 파일 하나 또는 텍스트 버퍼 하나를 한 번에 스캔합니다.
• 새 규칙은 워크스페이스 루트에 생성됩니다. 이동 및 삭제 작업은 Quipu 외부에서 수행됩니다.
• 스크래치 규칙은 컴파일하고 스캔할 수 있지만 저장하거나 캐시할 수는 없습니다.

기여 및 보안