mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-18 18:04:17 +00:00
fix(audit): reject special targets before reading content (#796)
A named pipe can block collection, integrity hashing or uncached skill metadata reads indefinitely. Require resolved regular files at each read boundary while preserving symlink accounting and integrity evidence. Cover the paths with bounded FIFO regressions and generated filesystem cases, and update the Nix vendor hash and integrity-rule documentation.
This commit is contained in:
@@ -135,7 +135,10 @@ func readSkillFrontmatter(skillMDPath string, fileCache map[string][]byte) (name
|
||||
if cached, ok := fileCache["SKILL.md"]; ok {
|
||||
data = cached
|
||||
} else {
|
||||
var err error
|
||||
info, err := os.Stat(skillMDPath)
|
||||
if err != nil || info.IsDir() || isSpecialMode(info.Mode()) {
|
||||
return "", ""
|
||||
}
|
||||
data, err = os.ReadFile(skillMDPath)
|
||||
if err != nil {
|
||||
return "", ""
|
||||
|
||||
@@ -2,6 +2,7 @@ package audit
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"io/fs"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
@@ -167,6 +168,7 @@ func scanSkillImpl(skillPath string, activeRules []rule, disabled map[string]boo
|
||||
// and integrity scans retain their upstream hidden-directory boundary.
|
||||
headerOnly := hiddenParent(normalizedRel)
|
||||
skipped := fi.Size() > maxScanFileSize || !isScannable(fi.Name())
|
||||
special := isSpecialMode(fi.Mode())
|
||||
var data []byte
|
||||
if fi.Mode().IsRegular() && fi.Name() != ".git" && !utils.IsOSMetadataFile(fi.Name()) {
|
||||
var headerErr error
|
||||
@@ -185,8 +187,11 @@ func scanSkillImpl(skillPath string, activeRules []rule, disabled map[string]boo
|
||||
skipped = true
|
||||
}
|
||||
} else if fi.Mode()&os.ModeSymlink != 0 {
|
||||
if target, err := os.Stat(path); err == nil && target.IsDir() {
|
||||
return nil
|
||||
if target, err := os.Stat(path); err == nil {
|
||||
if target.IsDir() {
|
||||
return nil
|
||||
}
|
||||
special = isSpecialMode(target.Mode())
|
||||
}
|
||||
}
|
||||
if headerOnly {
|
||||
@@ -219,6 +224,12 @@ func scanSkillImpl(skillPath string, activeRules []rule, disabled map[string]boo
|
||||
|
||||
totalBytes += size
|
||||
|
||||
// Keep logical accounting and integrity membership without opening a
|
||||
// stable special target (including one reached through a symlink).
|
||||
if special {
|
||||
result.SkippedFiles++
|
||||
return nil
|
||||
}
|
||||
if skipped {
|
||||
return nil
|
||||
}
|
||||
@@ -532,6 +543,9 @@ func scanFileImpl(filePath string, activeRules []rule, disabled map[string]bool)
|
||||
if info.IsDir() {
|
||||
return nil, fmt.Errorf("not a file: %s", filePath)
|
||||
}
|
||||
if isSpecialMode(info.Mode()) {
|
||||
return nil, fmt.Errorf("special file cannot be audited: %s", filePath)
|
||||
}
|
||||
|
||||
fileSize := info.Size()
|
||||
result := &Result{
|
||||
@@ -689,3 +703,7 @@ func ScanSkillsFilteredForProject(paths []string, projectRoot string, registry *
|
||||
}
|
||||
return outputs, nil
|
||||
}
|
||||
|
||||
func isSpecialMode(m fs.FileMode) bool {
|
||||
return m&(fs.ModeNamedPipe|fs.ModeSocket|fs.ModeDevice|fs.ModeCharDevice) != 0
|
||||
}
|
||||
|
||||
@@ -0,0 +1,65 @@
|
||||
package audit
|
||||
|
||||
import (
|
||||
"io/fs"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestSpecialMode(t *testing.T) {
|
||||
for _, tt := range []struct {
|
||||
mode fs.FileMode
|
||||
want bool
|
||||
}{
|
||||
{0, false}, {fs.ModeIrregular, false}, {fs.ModeSymlink, false},
|
||||
{fs.ModeNamedPipe, true}, {fs.ModeSocket, true}, {fs.ModeDevice, true}, {fs.ModeCharDevice, true},
|
||||
} {
|
||||
if got := isSpecialMode(tt.mode); got != tt.want {
|
||||
t.Errorf("mode %v: got %v, want %v", tt.mode, got, tt.want)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestCollectorNonTextAndDanglingLink(t *testing.T) {
|
||||
for _, tt := range []struct {
|
||||
name string
|
||||
linked, dangling bool
|
||||
want int
|
||||
}{
|
||||
{"regular", false, false, 1}, {"linked", true, false, 0}, {"dangling", true, true, 0},
|
||||
} {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
dir := filepath.Join(root, "skill")
|
||||
if err := os.Mkdir(dir, 0700); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := os.WriteFile(filepath.Join(dir, "SKILL.md"), []byte("# Skill\n"), 0600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
path := filepath.Join(dir, "logo.png")
|
||||
target := path
|
||||
if tt.linked {
|
||||
target = filepath.Join(root, "target.png")
|
||||
}
|
||||
if !tt.dangling {
|
||||
if err := os.WriteFile(target, []byte("ordinary asset"), 0600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
if tt.linked {
|
||||
if err := os.Symlink(target, path); err != nil {
|
||||
t.Skipf("symlink unavailable: %v", err)
|
||||
}
|
||||
}
|
||||
result, err := scanSkillImpl(dir, []rule{}, nil, nil)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if result.SkippedFiles != tt.want {
|
||||
t.Fatalf("got %d skipped files, want %d", result.SkippedFiles, tt.want)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,144 @@
|
||||
//go:build unix
|
||||
|
||||
package audit
|
||||
|
||||
import (
|
||||
"context"
|
||||
"os"
|
||||
"os/exec"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"syscall"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
// A blocked FIFO read must fail a regression without stranding a reader in
|
||||
// the test process. Each child owns only fixtures under its parent's temp dir.
|
||||
func TestCollectorSpecialFiles(t *testing.T) {
|
||||
const marker = "SKILLSHARE_TEST_COLLECTOR_SPECIAL"
|
||||
if fixture := os.Getenv(marker); fixture != "" {
|
||||
testCollectorSpecialFixture(t, fixture)
|
||||
return
|
||||
}
|
||||
for _, fixture := range []string{
|
||||
"direct", "direct-link", "walk", "walk-link", "walk-nontext",
|
||||
"pinned", "pinned-link", "metadata", "metadata-link",
|
||||
"metadata-pinned", "metadata-pinned-link",
|
||||
} {
|
||||
t.Run(fixture, func(t *testing.T) {
|
||||
root := t.TempDir()
|
||||
home := filepath.Join(root, "home")
|
||||
if err := os.Mkdir(home, 0700); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
|
||||
defer cancel()
|
||||
cmd := exec.CommandContext(ctx, os.Args[0], "-test.run=^TestCollectorSpecialFiles$", "-test.count=1")
|
||||
for _, entry := range os.Environ() {
|
||||
key, _, _ := strings.Cut(entry, "=")
|
||||
switch key {
|
||||
case "HOME", "TMPDIR", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_STATE_HOME", "XDG_CACHE_HOME",
|
||||
"CODEX_HOME", "CLAUDE_CONFIG_DIR", "PI_CODING_AGENT_DIR", "SKILLSHARE_CONFIG", marker:
|
||||
continue
|
||||
}
|
||||
cmd.Env = append(cmd.Env, entry)
|
||||
}
|
||||
cmd.Env = append(cmd.Env, marker+"="+fixture, "HOME="+home, "TMPDIR="+root,
|
||||
"XDG_CONFIG_HOME="+filepath.Join(home, "config"), "XDG_DATA_HOME="+filepath.Join(home, "data"),
|
||||
"XDG_STATE_HOME="+filepath.Join(home, "state"), "XDG_CACHE_HOME="+filepath.Join(home, "cache"))
|
||||
output, err := cmd.CombinedOutput() // CommandContext kills and reaps a blocked child.
|
||||
if ctx.Err() != nil {
|
||||
t.Fatalf("audit tried to read a stable special file; child deadline exceeded: %s", output)
|
||||
}
|
||||
if err != nil {
|
||||
t.Fatalf("fixture failed: %v\n%s", err, output)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func testCollectorSpecialFixture(t *testing.T, fixture string) {
|
||||
t.Helper()
|
||||
root := t.TempDir()
|
||||
skillDir := filepath.Join(root, "skill")
|
||||
if err := os.Mkdir(skillDir, 0700); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
const content = "# Ordinary instructions\n"
|
||||
if err := os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte(content), 0600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
name := "notes.md"
|
||||
metadata := strings.HasPrefix(fixture, "metadata")
|
||||
pinned := strings.Contains(fixture, "pinned")
|
||||
if metadata {
|
||||
name = "SKILL.md"
|
||||
} else if pinned || fixture == "walk-nontext" {
|
||||
// Exercise the skip count for a nontext FIFO.
|
||||
name = "payload.asset"
|
||||
}
|
||||
path := filepath.Join(skillDir, name)
|
||||
hashes := map[string]string{"SKILL.md": "sha256:" + sha256hex([]byte(content))}
|
||||
if pinned {
|
||||
if err := os.WriteFile(path, []byte(content), 0600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
hashes[name] = "sha256:" + sha256hex([]byte(content))
|
||||
}
|
||||
if !metadata || pinned {
|
||||
writeMetaWithHashes(t, skillDir, hashes)
|
||||
}
|
||||
if err := os.Remove(path); err != nil && !os.IsNotExist(err) {
|
||||
t.Fatal(err)
|
||||
}
|
||||
target := path
|
||||
if strings.HasSuffix(fixture, "-link") {
|
||||
target = filepath.Join(root, "target.fifo")
|
||||
}
|
||||
if err := syscall.Mkfifo(target, 0600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if target != path {
|
||||
if err := os.Symlink(target, path); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
if strings.HasPrefix(fixture, "direct") {
|
||||
if result, err := ScanFile(path); err == nil || result != nil {
|
||||
t.Fatalf("direct special file must be rejected: result=%+v err=%v", result, err)
|
||||
}
|
||||
return
|
||||
}
|
||||
result, err := ScanSkill(skillDir) // Include default integrity and metadata analyzers.
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if result.SkippedFiles != 1 {
|
||||
t.Errorf("special file counted %d skips, want 1", result.SkippedFiles)
|
||||
}
|
||||
info, err := os.Lstat(path)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
wantBytes := info.Size()
|
||||
if !metadata {
|
||||
wantBytes += int64(len(content))
|
||||
}
|
||||
if result.TotalBytes != wantBytes {
|
||||
t.Errorf("logical entry accounting changed: got %d bytes, want %d", result.TotalBytes, wantBytes)
|
||||
}
|
||||
if metadata && !pinned {
|
||||
return
|
||||
}
|
||||
wantPattern, wantSeverity := "content-unexpected", SeverityLow
|
||||
if pinned {
|
||||
wantPattern, wantSeverity = "content-tampered", SeverityMedium
|
||||
}
|
||||
for _, finding := range result.Findings {
|
||||
if finding.File == name && finding.Pattern == wantPattern && finding.Severity == wantSeverity {
|
||||
return
|
||||
}
|
||||
}
|
||||
t.Fatalf("missing %s evidence for %s: %+v", wantPattern, name, result.Findings)
|
||||
}
|
||||
@@ -64,6 +64,20 @@ func checkContentIntegrity(skillPath string, cache map[string][]byte, allFiles m
|
||||
if info.IsDir() {
|
||||
continue
|
||||
}
|
||||
if isSpecialMode(info.Mode()) {
|
||||
findings = append(findings, Finding{
|
||||
Severity: SeverityMedium,
|
||||
Pattern: "content-tampered",
|
||||
Message: fmt.Sprintf("pinned path resolves to a special file: %s", rel),
|
||||
File: rel,
|
||||
Line: 0,
|
||||
RuleID: "content-tampered",
|
||||
Analyzer: AnalyzerIntegrity,
|
||||
Category: CategoryIntegrity,
|
||||
Confidence: 1.0,
|
||||
})
|
||||
continue
|
||||
}
|
||||
if info.Size() > maxScanFileSize {
|
||||
findings = append(findings, Finding{
|
||||
Severity: SeverityMedium,
|
||||
|
||||
@@ -190,14 +190,14 @@ headers are INFO. This does not analyze runtime behavior or archive members.
|
||||
from header reads; the existing source-link policy and six-level depth limit stay
|
||||
in effect. There is no file-count cap; directory scans count header read failures as skipped
|
||||
and continue. An unreadable direct-file target still returns an error. Hidden
|
||||
directories receive header classification only; file symlinks keep existing text
|
||||
scanning. Hidden names alone do not imply disguise. HIGH requires a document,
|
||||
directories receive header classification only; links to non-special files keep existing text scanning. Special targets are
|
||||
skipped; direct audits of them return an error. Hidden names alone do not imply disguise. HIGH requires a document,
|
||||
image or configuration extension or a `.cache`/`__pycache__` parent directory;
|
||||
other native binaries, including `.venv/bin/python`, are MEDIUM.
|
||||
JSON results and summaries expose `binaryFiles`, `skippedFiles`, `oversizedFiles`;
|
||||
CLI and dashboard summaries show the same counts; the dashboard, Markdown and SARIF also report per-resource counts. Skipped includes read failures, binary,
|
||||
unsupported, oversized and regular files below hidden directories, so the counters
|
||||
overlap. Links and special files are not counted just for skipping header reads. Header
|
||||
overlap. Special files and links to special targets outside hidden directories count as skipped; other links are not counted just for skipping header reads. Header
|
||||
bytes are not auditable text. The rules `disguised-executable`, `python-bytecode`,
|
||||
`executable-artifact`, `archive-artifact`, `uncertain-header` can be disabled by ID
|
||||
with `enabled: false` in `audit-rules.yaml`.
|
||||
|
||||
@@ -334,7 +334,7 @@ The audit scans text-based files in skill directories:
|
||||
|
||||
Text scanning skips hidden directories and is recursive within the remaining skill directory, so `SKILL.md`, nested `references/*.md`, and `scripts/*.sh` are all inspected when they match supported text file types.
|
||||
|
||||
Before text filtering, audit checks the first 512 bytes of each regular file (and reads a bounded PE header at its declared offset when needed) to classify executables, CPython bytecode, ZIP/JAR archives, and disguised shebang scripts. Hidden directories receive header classification only; `__pycache__` is also included. Symlinked files retain their existing text scanning; `.git`, `.skillshare`, internal metadata, OS metadata, symlinks and special files are excluded from header reads. Binary and oversized files receive no full text analysis. Summaries report `binaryFiles`, `skippedFiles` and `oversizedFiles`; these counts overlap. Header classification does not analyze runtime behavior or archive contents. See [Executable and archive headers](../../understand/audit-engine.md#executable-headers) for formats, severity and limits. The structure analyzer also reads the skill’s `.claude/settings.json` and `.claude/settings.local.json` for [bundled hooks and settings](../../understand/audit-engine.md#bundled-hooks-and-settings).
|
||||
Before text filtering, audit checks the first 512 bytes of each regular file (and reads a bounded PE header at its declared offset when needed) to classify executables, CPython bytecode, ZIP/JAR archives, and disguised shebang scripts. Hidden directories receive header classification only; `__pycache__` is also included. Symlinks to non-special files retain their existing text scanning; special targets are skipped and direct audits of them return an error; `.git`, `.skillshare`, internal metadata, OS metadata, symlinks and special files are excluded from header reads. Binary and oversized files receive no full text analysis. Summaries report `binaryFiles`, `skippedFiles` and `oversizedFiles`; these counts overlap. Header classification does not analyze runtime behavior or archive contents. See [Executable and archive headers](../../understand/audit-engine.md#executable-headers) for formats, severity and limits. The structure analyzer also reads the skill’s `.claude/settings.json` and `.claude/settings.local.json` for [bundled hooks and settings](../../understand/audit-engine.md#bundled-hooks-and-settings).
|
||||
|
||||
## Options
|
||||
|
||||
|
||||
@@ -120,7 +120,7 @@ Skills installed or updated via `skillshare install` or `skillshare update` have
|
||||
|
||||
| Pattern | Severity | Description |
|
||||
|---------|----------|------------|
|
||||
| `content-tampered` | MEDIUM | A file's SHA-256 hash no longer matches the recorded hash |
|
||||
| `content-tampered` | MEDIUM | A file's SHA-256 hash no longer matches the recorded hash, or the pinned path now resolves to a special file |
|
||||
| `content-oversize` | MEDIUM | A pinned file exceeds the 1 MB scan size limit |
|
||||
| `content-missing` | LOW | A file recorded in metadata no longer exists on disk |
|
||||
| `content-unexpected` | LOW | A new file exists that was not recorded in metadata (OS metadata files such as `.DS_Store` are ignored) |
|
||||
@@ -450,7 +450,7 @@ The pinned magic table covers final CPython **3.6–3.14** formats. Unknown CRLF
|
||||
|
||||
CPython 3.6 uses a 12-byte header without flags; versions 3.7–3.14 use a 16-byte header and supported flags. For direct-file scans only the filename is used for disguise classification; ancestor directories do not affect the result.
|
||||
|
||||
The existing depth limit remains six directory levels. `.git`, `.skillshare`, `.skillshare-meta.json`, OS metadata, file symlinks and special files are excluded from header reads; directory symlinks are not traversed. Explicitly configured first-level source links retain their existing resolution policy. There is no file-count cap; directory scans count files with header read errors as skipped and continue scanning other files; an unreadable direct-file target still returns an error. Files below hidden directories receive header classification only, without gaining text-rule or integrity scanning. Symlinked files retain their existing text scanning, including direct-file and agent audits.
|
||||
The existing depth limit remains six directory levels. `.git`, `.skillshare`, `.skillshare-meta.json`, OS metadata, file symlinks and special files are excluded from header reads; directory symlinks are not traversed. Explicitly configured first-level source links retain their existing resolution policy. There is no file-count cap; directory scans count files with header read errors as skipped and continue scanning other files; an unreadable direct-file target still returns an error. Files below hidden directories receive header classification only, without gaining text-rule or integrity scanning. Symlinks to non-special files retain their existing text scanning; special targets are skipped and direct audits of them return an error, including direct-file and agent audits.
|
||||
|
||||
Header classification does not analyze runtime behavior, decode bytecode, or inspect archive members. Oversized files receive only a header check from this classifier. These findings belong to the `static` analyzer and can be disabled by rule ID with `enabled: false` in `audit-rules.yaml`.
|
||||
|
||||
@@ -468,7 +468,7 @@ When analyzability drops below **70%**, the audit engine emits an `INFO`-level f
|
||||
|
||||
Binary and unsupported files up to 1 MB count toward `totalBytes`, but not `auditableBytes`. Oversized files are excluded from the directory byte ratio; internal metadata and excluded paths are not counted.
|
||||
|
||||
CLI, JSON and dashboard summaries separately report `binaryFiles`, `skippedFiles`, and `oversizedFiles`. `skippedFiles` counts files without full text analysis, including read failures, binaries, unsupported extensions, oversized files and regular files below hidden directories. Links and special files are not counted merely because header reads skip them. `binaryFiles` includes recognized binary/archive headers and NUL-containing headers. These counts overlap: an oversized binary contributes to all three, once per counter. Header bytes never count as auditable text. Markdown reports add a `Skipped files` summary row and a `File coverage by resource` table, and SARIF runs carry the per-resource counts in `runs[].properties.skillshareCoverage`.
|
||||
CLI, JSON and dashboard summaries separately report `binaryFiles`, `skippedFiles`, and `oversizedFiles`. `skippedFiles` counts files without full text analysis, including read failures, binaries, unsupported extensions, oversized files and regular files below hidden directories. Special files and links to special targets outside hidden directories count as skipped; other links are not counted merely because header reads skip them. `binaryFiles` includes recognized binary/archive headers and NUL-containing headers. These counts overlap: an oversized binary contributes to all three, once per counter. Header bytes never count as auditable text. Markdown reports add a `Skipped files` summary row and a `File coverage by resource` table, and SARIF runs carry the per-resource counts in `runs[].properties.skillshareCoverage`.
|
||||
|
||||
### Output
|
||||
|
||||
|
||||
@@ -334,7 +334,7 @@ audit は Skill ディレクトリ内のテキストベースのファイルを
|
||||
|
||||
テキストスキャンは隠しディレクトリを除き、各 Skill ディレクトリ内で再帰的に行われるため、サポート対象のテキストファイルタイプに一致する限り、`SKILL.md`、ネストした `references/*.md`、`scripts/*.sh` もすべて検査されます。
|
||||
|
||||
テキストの絞り込み前に、audit は通常ファイルごとに先頭 512 バイトを読み、実行形式、CPython バイトコード、ZIP/JAR、偽装した shebang スクリプトを分類します。隠しディレクトリはヘッダー分類のみで、`__pycache__` も対象です。ファイルのシンボリックリンクは従来のテキスト解析を維持します。`.git`、`.skillshare`、内部・OS メタデータ、リンクと特殊ファイルはヘッダーを読みません。バイナリとサイズ超過ファイルは全文テキスト解析しません。サマリーは `binaryFiles`、`skippedFiles`、`oversizedFiles` を報告し、これらは重複して数えられます。実行動作とアーカイブ内部は解析しません。形式・重大度・上限は[実行形式とアーカイブのヘッダー](../../understand/audit-engine.md#executable-headers)を参照してください。 PE ヘッダーが範囲外の場合は、その位置から必要なバイト数だけ追加で読み取ります。 structure アナライザーは [同梱フックと設定](../../understand/audit-engine.md#bundled-hooks-and-settings) のために skill 内の `.claude/settings.json` と `.claude/settings.local.json` も読み取ります。
|
||||
テキストの絞り込み前に、audit は通常ファイルごとに先頭 512 バイトを読み、実行形式、CPython バイトコード、ZIP/JAR、偽装した shebang スクリプトを分類します。隠しディレクトリはヘッダー分類のみで、`__pycache__` も対象です。特殊ファイル以外へのリンクは従来のテキスト解析を維持します。特殊ファイルへのリンクはスキップされ、直接監査ではエラーになります。`.git`、`.skillshare`、内部・OS メタデータ、リンクと特殊ファイルはヘッダーを読みません。バイナリとサイズ超過ファイルは全文テキスト解析しません。サマリーは `binaryFiles`、`skippedFiles`、`oversizedFiles` を報告し、これらは重複して数えられます。実行動作とアーカイブ内部は解析しません。形式・重大度・上限は[実行形式とアーカイブのヘッダー](../../understand/audit-engine.md#executable-headers)を参照してください。 PE ヘッダーが範囲外の場合は、その位置から必要なバイト数だけ追加で読み取ります。 structure アナライザーは [同梱フックと設定](../../understand/audit-engine.md#bundled-hooks-and-settings) のために skill 内の `.claude/settings.json` と `.claude/settings.local.json` も読み取ります。
|
||||
|
||||
## オプション
|
||||
|
||||
|
||||
@@ -120,7 +120,7 @@ Markdown(`.md`)ファイルでは、フェンス付き・インデントさ
|
||||
|
||||
| パターン | 深刻度 | 説明 |
|
||||
|---------|----------|------------|
|
||||
| `content-tampered` | MEDIUM | ファイルの SHA-256 ハッシュが記録されたハッシュと一致しない |
|
||||
| `content-tampered` | MEDIUM | ファイルの SHA-256 ハッシュが記録されたハッシュと一致しない、または固定されたパスが特殊ファイルを指すようになった |
|
||||
| `content-oversize` | MEDIUM | pin されたファイルが 1 MB のスキャンサイズ上限を超えている |
|
||||
| `content-missing` | LOW | メタデータに記録されたファイルがディスク上に存在しない |
|
||||
| `content-unexpected` | LOW | メタデータに記録されていない新しいファイルが存在する(`.DS_Store` などの OS メタデータファイルは除く) |
|
||||
@@ -431,11 +431,11 @@ _cross-skill
|
||||
|
||||
CPython 3.6 はフラグのない 12 バイトのヘッダーを使い、3.7–3.14 は対応フラグを含む 16 バイトのヘッダーを使います。 単一ファイルのスキャンでは偽装判定にファイル名のみを使用し、親ディレクトリは影響しません。
|
||||
|
||||
深さは従来どおり 6 階層です。`.git`、`.skillshare`、`.skillshare-meta.json`、OS メタデータ、ファイルのシンボリックリンクと特殊ファイルはヘッダーを読みません。ディレクトリのリンクもたどりません。設定済みの最上位 source link の解決規則は維持します。ファイル数の上限はありません。ディレクトリのスキャンではヘッダーを読み取れないファイルを skipped として数え、他のファイルの解析を続けます。直接指定したファイルが読めない場合はエラーになります。隠しディレクトリ内ではヘッダーのみを分類し、テキストルールや整合性チェックの対象は増やしません。ファイルのシンボリックリンクは、直接ファイル・agent の監査を含め、従来のテキスト解析を維持します。
|
||||
深さは従来どおり 6 階層です。`.git`、`.skillshare`、`.skillshare-meta.json`、OS メタデータ、ファイルのシンボリックリンクと特殊ファイルはヘッダーを読みません。ディレクトリのリンクもたどりません。設定済みの最上位 source link の解決規則は維持します。ファイル数の上限はありません。ディレクトリのスキャンではヘッダーを読み取れないファイルを skipped として数え、他のファイルの解析を続けます。直接指定したファイルが読めない場合はエラーになります。隠しディレクトリ内ではヘッダーのみを分類し、テキストルールや整合性チェックの対象は増やしません。特殊ファイル以外へのリンクは従来のテキスト解析を維持します。特殊ファイルへのリンクはスキップされ、直接監査ではエラーになります。
|
||||
|
||||
この分類は実行時の動作、バイトコードのデコード、アーカイブ内部を解析しません。サイズ超過ファイルはこの分類器によるヘッダー検査のみです。各ルール ID は `audit-rules.yaml` の `enabled: false` で無効化できます。
|
||||
|
||||
隠し名だけでは偽装と判定しません。通常のツール用スクリプトは検出されず、`.venv/bin/python` などのネイティブバイナリは MEDIUM です。HIGH には文書・画像・設定用の拡張子、または `.cache`/`__pycache__` の親ディレクトリが必要です。リンク・特殊ファイルは、ヘッダー読み取りを省略しただけでは `skippedFiles` に数えません。
|
||||
隠し名だけでは偽装と判定しません。通常のツール用スクリプトは検出されず、`.venv/bin/python` などのネイティブバイナリは MEDIUM です。HIGH には文書・画像・設定用の拡張子、または `.cache`/`__pycache__` の親ディレクトリが必要です。隠しディレクトリ外の特殊ファイルとそのリンクは `skippedFiles` に数えます。他のリンクはヘッダー読み取りを省略しただけでは数えません。
|
||||
|
||||
## 分析可能性スコア(Analyzability Score) {#analyzability-score}
|
||||
|
||||
|
||||
@@ -334,7 +334,7 @@ audit는 skill 디렉터리 내 텍스트 기반 파일을 스캔합니다:
|
||||
|
||||
텍스트 스캔은 숨김 디렉터리를 제외하고 각 skill 디렉터리 내에서 재귀적으로 수행되므로, `SKILL.md`, 중첩된 `references/*.md`, `scripts/*.sh` 모두 지원되는 텍스트 파일 형식에 해당하면 검사됩니다.
|
||||
|
||||
텍스트 필터링 전에 audit은 일반 파일마다 처음 512바이트를 읽어 실행 형식, CPython 바이트코드, ZIP/JAR, 위장 shebang 스크립트를 분류합니다. 숨김 디렉터리에서는 헤더만 분류하며 `__pycache__`도 포함합니다. 파일 심볼릭 링크는 기존 텍스트 검사를 유지합니다. `.git`, `.skillshare`, 내부·OS 메타데이터, 링크 및 특수 파일은 헤더를 읽지 않습니다. 바이너리와 크기 초과 파일은 전체 텍스트 분석을 하지 않습니다. 요약의 `binaryFiles`, `skippedFiles`, `oversizedFiles`는 중복 집계될 수 있습니다. 실행 동작과 아카이브 내부는 분석하지 않습니다. 형식·심각도·제한은 [실행 파일 및 아카이브 헤더](../../understand/audit-engine.md#executable-headers)를 참고하세요. PE 헤더가 범위 밖에 있으면 해당 위치에서 필요한 바이트만 추가로 읽습니다. structure 분석기는 [번들 훅과 설정](../../understand/audit-engine.md#bundled-hooks-and-settings)을 위해 skill의 `.claude/settings.json`과 `.claude/settings.local.json`도 읽습니다.
|
||||
텍스트 필터링 전에 audit은 일반 파일마다 처음 512바이트를 읽어 실행 형식, CPython 바이트코드, ZIP/JAR, 위장 shebang 스크립트를 분류합니다. 숨김 디렉터리에서는 헤더만 분류하며 `__pycache__`도 포함합니다. 특수 파일이 아닌 대상을 가리키는 링크는 기존 텍스트 검사를 유지합니다. 특수 파일 대상은 건너뛰며 직접 감사하면 오류가 발생합니다. `.git`, `.skillshare`, 내부·OS 메타데이터, 링크 및 특수 파일은 헤더를 읽지 않습니다. 바이너리와 크기 초과 파일은 전체 텍스트 분석을 하지 않습니다. 요약의 `binaryFiles`, `skippedFiles`, `oversizedFiles`는 중복 집계될 수 있습니다. 실행 동작과 아카이브 내부는 분석하지 않습니다. 형식·심각도·제한은 [실행 파일 및 아카이브 헤더](../../understand/audit-engine.md#executable-headers)를 참고하세요. PE 헤더가 범위 밖에 있으면 해당 위치에서 필요한 바이트만 추가로 읽습니다. structure 분석기는 [번들 훅과 설정](../../understand/audit-engine.md#bundled-hooks-and-settings)을 위해 skill의 `.claude/settings.json`과 `.claude/settings.local.json`도 읽습니다.
|
||||
|
||||
## 옵션
|
||||
|
||||
|
||||
@@ -120,7 +120,7 @@ Markdown(`.md`) 파일에서는 펜스 및 들여쓰기 코드 블록과 파싱
|
||||
|
||||
| 패턴 | 심각도 | 설명 |
|
||||
|---------|----------|------------|
|
||||
| `content-tampered` | MEDIUM | 파일의 SHA-256 해시가 기록된 해시와 더 이상 일치하지 않음 |
|
||||
| `content-tampered` | MEDIUM | 파일의 SHA-256 해시가 기록된 해시와 더 이상 일치하지 않거나 대상이 특수 파일로 바뀜 |
|
||||
| `content-oversize` | MEDIUM | pin된 파일이 1MB 스캔 크기 제한을 초과함 |
|
||||
| `content-missing` | LOW | 메타데이터에 기록된 파일이 디스크에 더 이상 존재하지 않음 |
|
||||
| `content-unexpected` | LOW | 메타데이터에 기록되지 않은 새 파일이 존재함 (`.DS_Store` 같은 OS 메타데이터 파일은 제외) |
|
||||
@@ -430,11 +430,11 @@ _cross-skill
|
||||
|
||||
CPython 3.6은 플래그 없는 12바이트 헤더를 사용하며 3.7–3.14는 지원 플래그가 있는 16바이트 헤더를 사용합니다. 단일 파일 검사에서는 위장 분류에 파일 이름만 사용하며 상위 디렉터리는 영향을 주지 않습니다.
|
||||
|
||||
기존 깊이 제한 6단계를 유지합니다. `.git`, `.skillshare`, `.skillshare-meta.json`, OS 메타데이터, 파일 심볼릭 링크와 특수 파일은 헤더를 읽지 않으며 디렉터리 링크도 따라가지 않습니다. 명시적으로 설정한 최상위 source link의 기존 해석 정책은 유지합니다. 파일 수 제한은 없으며 디렉터리 스캔은 헤더를 읽지 못한 파일을 skipped로 세고 다른 파일을 계속 검사합니다. 직접 지정한 파일을 읽지 못하면 오류를 반환합니다. 숨김 디렉터리 안에서는 헤더만 분류하고 텍스트 규칙이나 무결성 검사를 추가하지 않습니다. 파일 심볼릭 링크는 직접 파일 및 agent 감사를 포함해 기존 텍스트 검사를 유지합니다.
|
||||
기존 깊이 제한 6단계를 유지합니다. `.git`, `.skillshare`, `.skillshare-meta.json`, OS 메타데이터, 파일 심볼릭 링크와 특수 파일은 헤더를 읽지 않으며 디렉터리 링크도 따라가지 않습니다. 명시적으로 설정한 최상위 source link의 기존 해석 정책은 유지합니다. 파일 수 제한은 없으며 디렉터리 스캔은 헤더를 읽지 못한 파일을 skipped로 세고 다른 파일을 계속 검사합니다. 직접 지정한 파일을 읽지 못하면 오류를 반환합니다. 숨김 디렉터리 안에서는 헤더만 분류하고 텍스트 규칙이나 무결성 검사를 추가하지 않습니다. 특수 파일이 아닌 대상을 가리키는 링크는 기존 텍스트 검사를 유지합니다. 특수 파일 대상은 건너뛰며 직접 감사하면 오류가 발생합니다.
|
||||
|
||||
헤더 분류는 실행 동작, 바이트코드 디코딩, 아카이브 내부를 분석하지 않습니다. 크기 초과 파일은 이 분류기의 헤더 검사만 받습니다. 각 규칙 ID는 `audit-rules.yaml`의 `enabled: false`로 비활성화할 수 있습니다.
|
||||
|
||||
숨김 이름만으로는 위장으로 판정하지 않습니다. 일반 도구 스크립트는 탐지하지 않으며 `.venv/bin/python` 같은 네이티브 바이너리는 MEDIUM입니다. HIGH에는 문서·이미지·설정 확장자 또는 `.cache`/`__pycache__` 상위 디렉터리가 필요합니다. 링크와 특수 파일은 헤더 읽기를 생략했다는 이유만으로 `skippedFiles`에 포함하지 않습니다.
|
||||
숨김 이름만으로는 위장으로 판정하지 않습니다. 일반 도구 스크립트는 탐지하지 않으며 `.venv/bin/python` 같은 네이티브 바이너리는 MEDIUM입니다. HIGH에는 문서·이미지·설정 확장자 또는 `.cache`/`__pycache__` 상위 디렉터리가 필요합니다. 숨김 디렉터리 밖의 특수 파일과 이를 가리키는 링크는 `skippedFiles`에 포함합니다. 다른 링크는 헤더 읽기 생략만으로 포함하지 않습니다.
|
||||
|
||||
## Analyzability Score {#analyzability-score}
|
||||
|
||||
|
||||
+1
-1
@@ -334,7 +334,7 @@ audit 会扫描 skill 目录中的文本类文件:
|
||||
|
||||
文本扫描跳过隐藏目录,在其余 skill 目录内递归进行,因此 `SKILL.md`、嵌套的 `references/*.md` 以及 `scripts/*.sh` 只要匹配受支持的文本文件类型,都会被检查。
|
||||
|
||||
文本过滤前,audit 对每个普通文件读取前 512 字节头部,分类可执行格式、CPython 字节码、ZIP/JAR 和伪装的 shebang 脚本。隐藏目录仅进行头部分类,`__pycache__` 也在范围内。文件符号链接保留原有文本扫描;`.git`、`.skillshare`、内部及操作系统元数据、链接和特殊文件不读取头部。二进制及超大文件不进行全文文本分析。摘要报告 `binaryFiles`、`skippedFiles`、`oversizedFiles`,计数可重叠。分类不分析运行行为或归档内容。格式、严重性及限制见[可执行文件和归档头部](../../understand/audit-engine.md#executable-headers)。 PE 头部超出窗口时,在指定偏移处额外读取有限字节。 structure 分析器还会读取 skill 内的 `.claude/settings.json` 和 `.claude/settings.local.json`,用于[随附的 hooks 与设置](../../understand/audit-engine.md#bundled-hooks-and-settings)。
|
||||
文本过滤前,audit 对每个普通文件读取前 512 字节头部,分类可执行格式、CPython 字节码、ZIP/JAR 和伪装的 shebang 脚本。隐藏目录仅进行头部分类,`__pycache__` 也在范围内。指向非特殊文件的链接保留原有文本扫描;特殊目标会被跳过,直接审计会返回错误;`.git`、`.skillshare`、内部及操作系统元数据、链接和特殊文件不读取头部。二进制及超大文件不进行全文文本分析。摘要报告 `binaryFiles`、`skippedFiles`、`oversizedFiles`,计数可重叠。分类不分析运行行为或归档内容。格式、严重性及限制见[可执行文件和归档头部](../../understand/audit-engine.md#executable-headers)。 PE 头部超出窗口时,在指定偏移处额外读取有限字节。 structure 分析器还会读取 skill 内的 `.claude/settings.json` 和 `.claude/settings.local.json`,用于[随附的 hooks 与设置](../../understand/audit-engine.md#bundled-hooks-and-settings)。
|
||||
|
||||
## 选项
|
||||
|
||||
|
||||
+3
-3
@@ -120,7 +120,7 @@ audit engine 会用 100 多条内置规则(正则表达式模式、表驱动
|
||||
|
||||
| 模式 | 严重级别 | 说明 |
|
||||
|---------|----------|------------|
|
||||
| `content-tampered` | MEDIUM | 文件的 SHA-256 哈希与记录的哈希不再匹配 |
|
||||
| `content-tampered` | MEDIUM | 文件的 SHA-256 哈希与记录的哈希不再匹配,或固定路径现在指向特殊文件 |
|
||||
| `content-oversize` | MEDIUM | 固定文件超过 1 MB 的扫描大小限制 |
|
||||
| `content-missing` | LOW | 元数据中记录的文件在磁盘上已不存在 |
|
||||
| `content-unexpected` | LOW | 存在一个未记录在元数据中的新文件(`.DS_Store` 等操作系统元数据文件除外) |
|
||||
@@ -430,11 +430,11 @@ _cross-skill
|
||||
|
||||
CPython 3.6 使用不含标志的 12 字节头部;3.7–3.14 使用含受支持标志的 16 字节头部。 直接扫描文件时,仅使用文件名判断伪装,祖先目录不会影响结果。
|
||||
|
||||
保留原有的六层深度限制。`.git`、`.skillshare`、`.skillshare-meta.json`、操作系统元数据、文件符号链接和特殊文件不读取头部;目录符号链接不会遍历。明确配置的顶层源链接继续使用原有解析策略。没有文件数量上限;目录扫描将头部读取失败的文件计入 skipped 并继续扫描其他文件;直接指定的文件无法读取时仍返回错误。隐藏目录中的文件仅分类头部,不增加文本规则或完整性扫描。文件符号链接保留原有文本扫描,包括直接文件和 agent 审计。
|
||||
保留原有的六层深度限制。`.git`、`.skillshare`、`.skillshare-meta.json`、操作系统元数据、文件符号链接和特殊文件不读取头部;目录符号链接不会遍历。明确配置的顶层源链接继续使用原有解析策略。没有文件数量上限;目录扫描将头部读取失败的文件计入 skipped 并继续扫描其他文件;直接指定的文件无法读取时仍返回错误。隐藏目录中的文件仅分类头部,不增加文本规则或完整性扫描。指向非特殊文件的链接保留原有文本扫描;特殊目标会被跳过,直接审计会返回错误。
|
||||
|
||||
头部分类不分析运行时行为、不解码字节码、不检查归档成员。超大文件仅接受此分类器的头部检查。可在 `audit-rules.yaml` 中按规则 ID 设置 `enabled: false` 来禁用这些发现。
|
||||
|
||||
隐藏名称本身不表示伪装:普通工具脚本保持无发现,`.venv/bin/python` 等原生二进制为 MEDIUM。HIGH 需要文档、图片、配置扩展名或 `.cache`/`__pycache__` 父目录。链接和特殊文件不会仅因跳过头部读取而计入 `skippedFiles`。
|
||||
隐藏名称本身不表示伪装:普通工具脚本保持无发现,`.venv/bin/python` 等原生二进制为 MEDIUM。HIGH 需要文档、图片、配置扩展名或 `.cache`/`__pycache__` 父目录。隐藏目录之外的特殊文件及指向它们的链接计入 `skippedFiles`;其他链接不会仅因跳过头部读取而计入。
|
||||
|
||||
## Analyzability Score {#analyzability-score}
|
||||
|
||||
|
||||
+1
-1
@@ -334,7 +334,7 @@ audit 會掃描 skill 目錄中的文字型檔案:
|
||||
|
||||
文字掃描略過隱藏目錄,在其餘 skill 目錄內遞迴進行,因此 `SKILL.md`、巢狀的 `references/*.md` 與 `scripts/*.sh` 只要符合支援的文字檔類型,都會被檢查。
|
||||
|
||||
文字篩選前,audit 對每個一般檔案讀取前 512 位元組標頭,分類執行格式、CPython 位元組碼、ZIP/JAR 與偽裝的 shebang 腳本。隱藏目錄僅分類標頭,`__pycache__` 也在範圍內。檔案符號連結保留既有文字掃描;`.git`、`.skillshare`、內部與作業系統 metadata、連結與特殊檔案不讀取標頭。二進位與超大檔案不進行全文文字分析。摘要回報 `binaryFiles`、`skippedFiles`、`oversizedFiles`,計數可重疊。分類不分析執行行為或封存內容。格式、嚴重性與限制見[執行檔與封存檔標頭](../../understand/audit-engine.md#executable-headers)。 PE 標頭超出範圍時,在指定偏移處額外讀取有限位元組。 structure 分析器也會讀取 skill 內的 `.claude/settings.json` 與 `.claude/settings.local.json`,用於[隨附的 hooks 與設定](../../understand/audit-engine.md#bundled-hooks-and-settings)。
|
||||
文字篩選前,audit 對每個一般檔案讀取前 512 位元組標頭,分類執行格式、CPython 位元組碼、ZIP/JAR 與偽裝的 shebang 腳本。隱藏目錄僅分類標頭,`__pycache__` 也在範圍內。指向非特殊檔案的連結保留既有文字掃描;特殊目標會被略過,直接稽核會回傳錯誤;`.git`、`.skillshare`、內部與作業系統 metadata、連結與特殊檔案不讀取標頭。二進位與超大檔案不進行全文文字分析。摘要回報 `binaryFiles`、`skippedFiles`、`oversizedFiles`,計數可重疊。分類不分析執行行為或封存內容。格式、嚴重性與限制見[執行檔與封存檔標頭](../../understand/audit-engine.md#executable-headers)。 PE 標頭超出範圍時,在指定偏移處額外讀取有限位元組。 structure 分析器也會讀取 skill 內的 `.claude/settings.json` 與 `.claude/settings.local.json`,用於[隨附的 hooks 與設定](../../understand/audit-engine.md#bundled-hooks-and-settings)。
|
||||
|
||||
## 選項
|
||||
|
||||
|
||||
+3
-3
@@ -120,7 +120,7 @@ Audit engine 會把 skill 目錄中每個以文字為主的檔案,拿去比對
|
||||
|
||||
| 模式 | 嚴重程度 | 說明 |
|
||||
|---------|----------|------------|
|
||||
| `content-tampered` | MEDIUM | 檔案的 SHA-256 雜湊值與記錄的雜湊值不再相符 |
|
||||
| `content-tampered` | MEDIUM | 檔案的 SHA-256 雜湊值與記錄的雜湊值不再相符,或固定路徑現在指向特殊檔案 |
|
||||
| `content-oversize` | MEDIUM | 已釘選的檔案超過 1 MB 的掃描大小限制 |
|
||||
| `content-missing` | LOW | metadata 中記錄的檔案在磁碟上已不存在 |
|
||||
| `content-unexpected` | LOW | 出現了未記錄在 metadata 中的新檔案(`.DS_Store` 等作業系統 metadata 檔案除外) |
|
||||
@@ -430,11 +430,11 @@ _cross-skill
|
||||
|
||||
CPython 3.6 使用不含旗標的 12 位元組標頭;3.7–3.14 使用含支援旗標的 16 位元組標頭。 直接掃描檔案時,只使用檔名判斷偽裝,祖先目錄不影響結果。
|
||||
|
||||
保留原有的六層深度限制。`.git`、`.skillshare`、`.skillshare-meta.json`、作業系統 metadata、檔案符號連結與特殊檔案不讀取標頭;目錄符號連結不會遍歷。明確設定的頂層來源連結沿用既有解析政策。沒有檔案數量上限;目錄掃描將標頭讀取失敗的檔案計入 skipped 並繼續掃描其他檔案;直接指定的檔案無法讀取時仍回傳錯誤。隱藏目錄內的檔案僅分類標頭,不新增文字規則或完整性掃描。檔案符號連結保留既有文字掃描,包括直接檔案與 agent 稽核。
|
||||
保留原有的六層深度限制。`.git`、`.skillshare`、`.skillshare-meta.json`、作業系統 metadata、檔案符號連結與特殊檔案不讀取標頭;目錄符號連結不會遍歷。明確設定的頂層來源連結沿用既有解析政策。沒有檔案數量上限;目錄掃描將標頭讀取失敗的檔案計入 skipped 並繼續掃描其他檔案;直接指定的檔案無法讀取時仍回傳錯誤。隱藏目錄內的檔案僅分類標頭,不新增文字規則或完整性掃描。指向非特殊檔案的連結保留既有文字掃描;特殊目標會被略過,直接稽核會回傳錯誤。
|
||||
|
||||
標頭分類不分析執行時行為、不解碼位元組碼、不檢查封存成員。超大檔案僅接受此分類器的標頭檢查。可在 `audit-rules.yaml` 中依規則 ID 設定 `enabled: false` 來停用這些發現。
|
||||
|
||||
隱藏名稱本身不表示偽裝:一般工具腳本保持無發現,`.venv/bin/python` 等原生二進位為 MEDIUM。HIGH 需要文件、圖片、設定副檔名或 `.cache`/`__pycache__` 父目錄。連結與特殊檔案不會僅因略過標頭讀取而計入 `skippedFiles`。
|
||||
隱藏名稱本身不表示偽裝:一般工具腳本保持無發現,`.venv/bin/python` 等原生二進位為 MEDIUM。HIGH 需要文件、圖片、設定副檔名或 `.cache`/`__pycache__` 父目錄。隱藏目錄外的特殊檔案及指向它們的連結計入 `skippedFiles`;其他連結不會僅因略過標頭讀取而計入。
|
||||
|
||||
## Analyzability Score {#analyzability-score}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user