Security

Threat model

licit operates as a local auditing tool. Its attack surface is limited, but there are risks to consider:

Identified threats

What licit does NOT do

• Does not execute arbitrary code from the files it analyzes.
• Does not send data to external servers. Everything is processed locally.
• Does not require elevated permissions. Operates with user-level permissions.
• Does not modify the source code of the analyzed project.
• Does not store credentials. Signing keys are managed by the user.

Cryptographic signing (provenance)

HMAC-SHA256

When provenance signing is enabled (provenance.sign: true), each record is signed with HMAC-SHA256:

signature = HMAC-SHA256(key, canonical_json(record))

Configuration:

provenance:
  sign: true
  sign_key_path: ~/.licit/signing-key

Key generation:

# Generate a 256-bit key
python3.12 -c "import secrets; print(secrets.token_hex(32))" > ~/.licit/signing-key
chmod 600 ~/.licit/signing-key

Attestation (Merkle tree)

licit implements a Merkle tree over provenance records to detect manipulation:

         root_hash
        /         \
    hash_01      hash_23
    /    \       /    \
 hash_0 hash_1 hash_2 hash_3
   |      |      |      |
 rec_0  rec_1  rec_2  rec_3

Any modification to a record invalidates the hash chain from that record up to the root.

Implementation:

• Each record is serialized as canonical JSON (sort_keys=True, default=str)
• SHA256 is calculated for each record, forming the tree leaves
• Hash pairs are concatenated and re-hashed up to the root
• Odd number of records: the last one is duplicated to complete the pair
• Individual verification uses hmac.compare_digest (timing-safe)

from licit.provenance.attestation import ProvenanceAttestor

attestor = ProvenanceAttestor()  # Auto-generates key in .licit/.signing-key

# Sign an individual record
sig = attestor.sign_record({"file": "app.py", "source": "ai"})

# Verify integrity
assert attestor.verify_record({"file": "app.py", "source": "ai"}, sig)

# Sign batch with Merkle tree
root = attestor.sign_batch([record1, record2, record3])

Key management

The signing key is resolved in this order:

1. Explicit path (sign_key_path in config)
2. Local fallback (.licit/.signing-key in the project)
3. Auto-generation (32 random bytes with os.urandom(32))

All filesystem accesses are protected with try/except OSError.

Data protection

Sensitive data generated by licit

Recommended .gitignore

# licit — sensitive data
.licit/provenance.jsonl
.licit/fria-data.json

# licit — signing key (if stored in the project)
.licit/signing-key
*.key

# licit — generated reports (optional, can be committed)
# .licit/reports/

Dependencies

Dependency auditing

licit uses 6 runtime dependencies, all widely adopted:

Recommendations

1. Pin versions in production: Use a requirements.txt or pip-compile to lock exact versions.

2. Audit regularly:

   pip audit                    # Search for known vulnerabilities
   pip install pip-audit && pip-audit  # Alternative

3. Verify hashes:

   pip install --require-hashes -r requirements.txt

Safe file parsing

YAML

licit always uses yaml.safe_load() to parse YAML. Never yaml.load() (which allows arbitrary Python code execution).

# Correct (what licit does)
data = yaml.safe_load(f.read())

# NEVER (vulnerable to code execution)
# data = yaml.load(f.read(), Loader=yaml.FullLoader)

JSON

For SARIF and other JSON files, standard json.load() is used, which is safe by design.

Agent configuration files

Files like CLAUDE.md, .cursorrules, AGENTS.md are read as plain text. licit does not interpret or execute their content — it only analyzes them to detect changes and extract metadata.

External process execution

licit executes git commands via subprocess.run() with the following protections:

• capture_output=True — stdout/stderr captured, not displayed directly.
• text=True — Automatic UTF-8 decoding.
• No shell=True — Arguments are passed as a list, not a string, preventing command injection.
• timeout=30 — Explicit 30-second timeout on git log to avoid blocking on massive repos (10 seconds for git show and existence checks).
• subprocess.TimeoutExpired caught — returns an empty list without crashing.
• Explicit check=False — on all subprocess.run calls in provenance and changelog (does not raise exceptions on returncode != 0).
• Size guard (changelog): ConfigWatcher._MAX_CONTENT_BYTES = 1_048_576 — discards git show content larger than 1 MB to prevent OOM with accidentally tracked binary files.

# How licit executes git commands
result = subprocess.run(
    ["git", "rev-list", "--count", "HEAD"],
    capture_output=True,
    text=True,
)

Vulnerability reporting

If you find a security vulnerability in licit:

1. Do not open a public issue.
2. Send an email to the maintainers with:
   • Description of the vulnerability
   • Steps to reproduce
   • Potential impact
3. You will receive a confirmation within 48 hours.
4. A fix and advisory will be published once resolved.

See SECURITY.md in the project root for contact information.