google/magika

Magika

Magika는 최근 딥러닝의 발전을 활용하여 정확한 파일 유형 탐지를 제공하는 새로운 AI 기반 파일 유형 탐지 도구입니다. 내부적으로 Magika는 수 MB에 불과한 맞춤형 고도로 최적화된 모델을 사용하며, 단일 CPU에서 실행할 때도 수 밀리초 내에 정밀한 파일 식별이 가능합니다. Magika는 200개 이상의 콘텐츠 유형(바이너리 및 텍스트 파일 형식 모두 포함)에 걸쳐 약 1억 개의 샘플로 구성된 데이터셋으로 훈련 및 평가되었으며, 테스트 세트에서 평균 약 99%의 정확도를 달성합니다.

다음은 Magika 명령줄 출력의 예입니다:

<p align="center"> <img src="./assets/magika-screenshot.png" width="600"> </p>

Magika는 Gmail, Drive 및 Safe Browsing 파일을 적절한 보안 및 콘텐츠 정책 스캐너로 라우팅하여 Google 사용자의 안전을 개선하는 데 대규모로 사용되며, 매주 수천억 개의 샘플을 처리합니다. Magika는 VirusTotal (예시) 및 abuse.ch (예시)와도 통합되었습니다.

자세한 내용은 Google OSS 블로그의 초기 발표 게시물을 읽거나, Magika 웹사이트를 참조하고, IEEE/ACM 국제 소프트웨어 공학 컨퍼런스(ICSE) 2025에 게재된 연구 논문에서 더 자세한 내용을 확인할 수 있습니다.

아무것도 설치하지 않고 웹 데모를 통해 Magika를 사용해 볼 수 있습니다. 이 데모는 브라우저에서 로컬로 실행됩니다!

주요 특징

• Rust로 작성된 명령줄 도구, Python API, Rust, JavaScript/TypeScript(실험적인 npm 패키지 포함, 웹 데모 구동) 및 GoLang(작업 중)용 추가 바인딩으로 제공됩니다.
• 200개 이상의 콘텐츠 유형에 걸쳐 약 1억 개의 파일로 구성된 데이터셋으로 훈련 및 평가되었습니다.
• 테스트 세트에서 Magika는 평균 약 99%의 정밀도와 재현율을 달성하여 기존 접근 방식(특히 텍스트 콘텐츠 유형)을 능가합니다.
• 모델 로드(일회성 오버헤드) 후 추론 시간은 단일 CPU에서 실행할 때도 파일당 약 5ms입니다.
• 동시에 수천 개의 파일에 대해 Magika를 호출할 수 있습니다. 또한 -r을 사용하여 디렉토리를 재귀적으로 스캔할 수 있습니다.
• 파일 크기와 관계없이 거의 일정한 추론 시간; Magika는 파일 콘텐츠의 제한된 하위 집합만 사용합니다.
• Magika는 콘텐츠 유형별 임계값 시스템을 사용하여 모델의 예측을 "신뢰"할지 아니면 "일반 텍스트 문서" 또는 "알 수 없는 바이너리 데이터"와 같은 일반 레이블을 반환할지 결정합니다.
• 오류 허용 오차는 high-confidence, medium-confidence, best-guess와 같은 다양한 예측 모드를 통해 제어할 수 있습니다.
• 클라이언트와 바인딩은 이미 오픈 소스이며, 더 많은 기능이 곧 제공될 예정입니다!

목차

1. 시작하기
2. 설치
3. 빠른 시작
4. 문서
5. 보안 취약점
6. 라이선스
7. 면책 조항

시작하기

설치

명령줄 도구

Magika는 Rust로 작성된 CLI를 제공하며 여러 가지 방법으로 설치할 수 있습니다.

magika Python 패키지를 통해:

pipx install magika

brew를 통해 (macOS / Linux):

brew install magika

설치 스크립트를 통해:

curl -LsSf https://securityresearch.google/magika/install.sh | sh

또는:

powershell -ExecutionPolicy Bypass -c "irm https://securityresearch.google/magika/install.ps1 | iex"

magika-cli Rust 패키지를 통해:

cargo install --locked magika-cli

Python 패키지

pip install magika

JavaScript 패키지

npm install magika

빠른 시작

다음은 시작하는 데 도움이 되는 몇 가지 빠른 예제입니다.

Magika의 내부 작동 방식에 대해 알아보려면 Magika 웹사이트의 핵심 개념 섹션을 참조하세요.

명령줄 도구 예제

% cd tests_data/basic && magika -r * | head
asm/code.asm: Assembly (code)
batch/simple.bat: DOS batch file (code)
c/code.c: C source (code)
css/code.css: CSS source (code)
csv/magika_test.csv: CSV document (code)
dockerfile/Dockerfile: Dockerfile (code)
docx/doc.docx: Microsoft Word 2007+ document (document)
docx/magika_test.docx: Microsoft Word 2007+ document (document)
eml/sample.eml: RFC 822 mail (text)
empty/empty_file: Empty file (inode)

% magika./tests_data/basic/python/code.py --json
[
  {
    "path": "./tests_data/basic/python/code.py",
    "result": {
      "status": "ok",
      "value": {
        "dl": {
          "description": "Python source",
          "extensions": [
            "py",
            "pyi"
          ],
          "group": "code",
          "is_text": true,
          "label": "python",
          "mime_type": "text/x-python"
        },
        "output": {
          "description": "Python source",
          "extensions": [
            "py",
            "pyi"
          ],
          "group": "code",
          "is_text": true,
          "label": "python",
          "mime_type": "text/x-python"
        },
        "score": 0.996999979019165
      }
    }
  }
]

% cat tests_data/basic/ini/doc.ini | magika -
-: INI configuration file (text)

% magika --help
Determines file content types using AI

Usage: magika [OPTIONS] [PATH]...

Arguments:
  [PATH]...
          분석할 파일 경로 목록.

          표준 입력에서 읽으려면 대시(-)를 사용하십시오(한 번만 사용 가능).

Options:
  -r, --recursive
          디렉토리 자체를 식별하는 대신 디렉토리 내의 파일을 식별합니다.

      --no-dereference
          심볼릭 링크를 따라 콘텐츠를 식별하는 대신 심볼릭 링크 자체를 식별합니다.

      --colors
          터미널 지원 여부와 관계없이 색상으로 출력합니다.

      --no-colors
          터미널 지원 여부와 관계없이 색상 없이 출력합니다.

  -s, --output-score
          콘텐츠 유형과 함께 예측 점수를 출력합니다.

  -i, --mime-type
          콘텐츠 유형 설명 대신 MIME 유형을 출력합니다.

  -l, --label
          콘텐츠 유형 설명 대신 간단한 레이블을 출력합니다.

      --json
          JSON 형식으로 출력합니다.

      --jsonl
          JSONL 형식으로 출력합니다.

      --format <CUSTOM>
          사용자 정의 형식으로 출력합니다(자세한 내용은 --help 사용).

          다음 플레이스홀더가 지원됩니다:

            %p  파일 경로
            %l  콘텐츠 유형을 식별하는 고유 레이블
            %d  콘텐츠 유형 설명
            %g  콘텐츠 유형 그룹
            %m  콘텐츠 유형의 MIME 유형
            %e  콘텐츠 유형의 가능한 파일 확장자
            %s  파일에 대한 콘텐츠 유형의 점수
            %S  파일에 대한 콘텐츠 유형의 점수(백분율)
            %b  재정의된 경우 모델 출력(그렇지 않으면 비어 있음)
            %%  리터럴 %

  -h, --help
          도움말 출력('-h'로 요약 보기)

  -V, --version
          버전 출력

CLI에 대한 더 많은 예제와 문서는 https://crates.io/crates/magika-cli를 참조하세요.

Python 예제

>>> from magika import Magika
>>> m = Magika()
>>> res = m.identify_bytes(b'function log(msg) {console.log(msg);}')
>>> print(res.output.label)
javascript

>>> from magika import Magika
>>> m = Magika()
>>> res = m.identify_path('./tests_data/basic/ini/doc.ini')
>>> print(res.output.label)
ini

>>> from magika import Magika
>>> m = Magika()
>>> with open('./tests_data/basic/ini/doc.ini', 'rb') as f:
>>>     res = m.identify_stream(f)
>>> print(res.output.label)
ini

Python 모듈에 대한 더 많은 예제와 문서는 Python Magika 모듈 섹션을 참조하세요.

문서

• 핵심 개념
• Magika 작동 방식
• 모델 및 콘텐츠 유형
• 예측 모드
• 출력 이해
• CLI 및 바인딩(Python 모듈, JavaScript 모듈 등)
• 기여
• FAQ

자세한 문서는 Magika 웹사이트를 참조하세요: -...

보안 취약점

[email protected]으로 직접 연락해 주십시오.

라이선스

Apache 2.0; 자세한 내용은 LICENSE를 참조하세요.

면책 조항

이 프로젝트는 공식 Google 프로젝트가 아닙니다. Google은 이 프로젝트를 지원하지 않으며, 특히 품질, 상품성 또는 특정 목적에의 적합성에 대한 모든 보증을 부인합니다.