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)

In future phases, licit will implement a Merkle tree over the provenance store to detect manipulation or deletion of records:

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

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

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 Audit

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                    # Checks for known vulnerabilities
   pip install pip-audit && pip-audit  # Alternative

3. Verify hashes:

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

Secure 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 secure 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.
• Implicit timeout on network operations (future).

# 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 at the project root for contact information.