DECEIVE

Imported from Cisco-Talos/DECEIVE (AGENTS.md). Install upstream with npx skills add Cisco-Talos/DECEIVE. Copyright stays with the author.

AGENTS.md - DECEIVE

This document gives AI coding agents the project-specific context needed to make consistent, idiomatic changes to DECEIVE.

Project Overview

DECEIVE, the DECeption with Evaluative Integrated Validation Engine, is a proof-of-concept high-interaction SSH honeypot. It accepts SSH connections, authenticates according to configurable honeypot account rules, sends attacker input to a configured LLM backend, returns realistic Linux-like command output, and writes JSON Lines telemetry for the full session.

The LLM-backed SSH interaction is DECEIVE's core simulation surface. The core engineering goal is to make that live interaction observable, bounded, testable, and believable without exposing a real shell or real filesystem.

Primary implementation files:

• SSH/ssh_server.py - AsyncSSH server, authentication, prompt assembly, LangChain message history, JSON logging, and runtime configuration.
• SSH/config.ini.TEMPLATE - tracked operator configuration template.
• SSH/prompt.txt - default user prompt describing the host being emulated.
• tests/ - unit and integration coverage for configuration, authentication, logging, session behavior, and real AsyncSSH connectivity with a fake LLM.
• README.md - user-facing setup, runtime, testing, and log format reference.
• TODO.txt - lightweight backlog and known priorities.

Start-Of-Work Checklist

For any non-trivial change:

1. Read README.md, pyproject.toml, and TODO.txt before editing.
2. Check git status --short; preserve user changes already in the tree.
3. Inspect the relevant tests before changing behavior.
4. Update TODO.txt only when the change completes, changes, or adds a tracked backlog item.
5. Update README.md and SSH/config.ini.TEMPLATE when setup, config keys, runtime behavior, or log fields change.

Tech Stack

• Python 3.11, pinned by .python-version and requires-python in pyproject.toml.
• uv for dependency management and command execution.
• asyncssh for the SSH server and integration test clients.
• LangChain provider integrations for OpenAI, Azure OpenAI, Ollama, AWS Bedrock, and Google Gemini.
• pytest and pytest-asyncio for automated tests.
• Standard library argparse, configparser, logging, json, asyncio, and path utilities. The current CLI is argparse-based; do not switch frameworks unless explicitly requested.

Dependency Management

Use uv; do not add requirements.txt or install dependencies with bare pip.

Common commands:

uv sync
uv run pytest
uv run pytest tests/test_ssh_server_unit.py
uv run pytest tests/test_ssh_integration.py
uv run python SSH/ssh_server.py

When adding or removing dependencies, update pyproject.toml and uv.lock together. This project currently has package = false, so treat it as a script repository rather than an installed Python package.

Code Style

• Prefer clear, direct Python over clever abstractions.
• Add type hints for new or significantly changed functions. Existing code is still being modernized, so avoid broad type-only churn.
• Use specific exceptions and actionable error messages at runtime boundaries.
• Avoid bare except Exception in new code unless it is at main() or another intentional process boundary.
• Prefer pathlib.Path for new path-heavy code, but match nearby code when a small change in SSH/ssh_server.py would otherwise create needless churn.
• Keep lines readable, around 100 characters where practical.
• Use comments sparingly for non-obvious async, logging, or security behavior.
• Do not add linting or formatting tool mandates unless the project config is updated to support them.

Runtime Architecture

SSH Server

start_server() creates an AsyncSSH listener from the active config. Preserve these behavior contracts:

• listen_host may constrain binding; tests use 127.0.0.1.
• port = 0 must work in tests to request a random local port.
• Host private keys are resolved relative to the loaded config file first, then relative to SSH/.
• The server version string intentionally imitates OpenSSH.
• The process handler must never grant access to a real local shell.

MySSHServer owns SSH connection/auth callbacks. handle_client() owns interactive and non-interactive command handling. There is known cleanup work in TODO.txt around lifecycle ownership; avoid deepening the split between server instances and process handling.

Authentication Semantics

The honeypot intentionally supports deceptive login modes:

• username = accepts login without a password.
• username = secret requires the exact password.
• username = * accepts any password, including empty passwords.
• Unknown usernames currently authenticate like wildcard accounts.

Do not "fix" the unknown-user behavior unless implementing an explicit auth policy option. Tests should cover all four modes.

LLM Simulation

build_message_history() composes:

1. The configured system prompt from [llm].system_prompt.
2. The user prompt from --prompt, --prompt-file, or SSH/prompt.txt.
3. Per-session message history trimmed to trimmer_max_tokens.

Preserve per-session isolation through llm_sessions and the session id passed in LangChain config. Runtime supports provider selection through choose_llm(); new providers should be small, testable branches with provider-specific config kept in SSH/config.ini.TEMPLATE.

Interactive and non-interactive behavior differs:

• Interactive sessions receive an initial banner/MOTD and shell prompt.
• Interactive responses should end with a realistic shell prompt.
• Non-interactive command output must not include a prompt or MOTD.
• If an input would close the login shell, the model should return exactly YYY-END-OF-SESSION-YYY.

The LLM may hallucinate future user input. When changing prompts or response handling, preserve the rule that DECEIVE answers only the current input and does not invent the attacker's next command.

Logging Contracts

DECEIVE logs JSON Lines to the configured honeypot.log_file. Relative log paths are resolved from the directory containing the loaded config file.

Preserve these fields for session telemetry:

• timestamp - UTC ISO 8601 with millisecond precision.
• level
• task_name - the stable session-... id for the SSH session.
• src_ip, src_port, dst_ip, dst_port
• message
• sensor_name
• sensor_protocol - currently ssh

Important message types:

• SSH connection received
• User attempting to authenticate
• Authentication success
• Authentication failed
• User input
• LLM response
• Session summary
• SSH connection closed

User input and LLM response records store full content in details as base64-encoded UTF-8. Keep that encoding contract stable so arbitrary terminal bytes do not break JSON logs. Include the interactive boolean for command and response records where it applies.

Session summary records include details with the LLM summary and judgement as one of BENIGN, SUSPICIOUS, MALICIOUS, or UNKNOWN. Generate at most one summary per session.

This is a honeypot: authentication logs intentionally include attempted usernames and passwords. Do not remove that behavior casually, but also do not log provider API keys, environment variables, local config contents, or stack traces containing secrets.

Configuration And Local Artifacts

Tracked:

• SSH/config.ini.TEMPLATE
• SSH/prompt.txt

Ignored/local:

• SSH/config.ini
• SSH host keys such as SSH/ssh_host_key, SSH/deceive_host_key, and *.pub
• *.log files including honeypot logs
• .venv/, .pytest_cache/, and other generated Python artifacts

Do not commit local credentials, provider API keys, host private keys, generated logs, or deployment artifacts under SSH/DEPLOY/.

When adding config settings:

1. Add the setting to SSH/config.ini.TEMPLATE with a clear comment.
2. Provide a sane default in load_config() if the server can run without an explicit config file.
3. Add CLI overrides only when operators need them.
4. Cover config-file-relative behavior in tests when paths are involved.
5. Update README.md.

Testing Requirements

All tests must be deterministic and must not call a live LLM provider. Use fake message history objects, monkeypatched provider classes, or injected message_history objects.

Testing conventions:

• Use tmp_path for config files, host keys, logs, and any file I/O.
• Bind integration servers to 127.0.0.1 and port = 0.
• Use known_hosts=None for ephemeral local AsyncSSH clients in tests.
• Flush and close log handlers in fixtures to avoid leaking global state.
• Reset module globals such as config, accounts, llm_sessions, and with_message_history after tests that mutate runtime state.
• Assert log shape, base64 encoding, session id consistency, and one summary per session when touching session flow.

Run at least the focused test file for the code you changed. Run the full suite before commits or behavior-heavy changes:

uv run pytest

Security And Safety

DECEIVE is a proof of concept, not production-ready infrastructure. Keep that warning intact in user-facing docs unless the security posture materially changes.

Prioritize bounded resource controls for public-facing behavior:

• Maximum input line length.
• Session idle and total timeouts.
• Connection and request limits.
• LLM call throttling.
• Cleanup for per-session message history.

Never route attacker input to a real shell or filesystem. The LLM should simulate output only. If adding tools, retrieval, file access, or command execution, gate them behind explicit design review and tests that prove attacker input cannot escape the simulation boundary.

Documentation Checklist

Update docs when behavior changes:

• README.md for setup, running, operator behavior, log schema, or warnings.
• SSH/config.ini.TEMPLATE for config changes.
• SSH/prompt.txt only for default emulation behavior.
• TODO.txt for backlog changes or completed tracked priorities.
• Tests for every observable auth, session, config, prompt, or logging contract.

Versioning And Commits

The project version currently lives in pyproject.toml only. If asked to bump the version, update pyproject.toml, run uv sync so uv.lock stays consistent, and document the reason in the commit.

Prefer Conventional Commit prefixes such as feat:, fix:, docs:, test:, refactor:, and chore: when committing.

Known Design Decisions

• DECEIVE intentionally logs usernames and passwords supplied to the honeypot.
• Unknown usernames currently authenticate successfully to maximize deception.
• LLM calls are part of runtime behavior; only tests should replace them with deterministic fakes.
• Relative log_file paths resolve next to the loaded config file, not necessarily the current working directory.
• The default implementation currently lives mostly in one script. Refactor incrementally and keep compatibility with documented commands.