From 95190946e089451468b8378702f7c80ddb1df8ad Mon Sep 17 00:00:00 2001 From: anti Date: Sun, 12 Apr 2026 03:42:08 -0400 Subject: [PATCH] moved: AST graphs into develpment/ folder --- development/ast_graph.md | 419 ++++++++++++++++++++++++ development/complete_execution_graph.md | 192 +++++++++++ development/execution_graphs.md | 66 ++++ 3 files changed, 677 insertions(+) create mode 100644 development/ast_graph.md create mode 100644 development/complete_execution_graph.md create mode 100644 development/execution_graphs.md diff --git a/development/ast_graph.md b/development/ast_graph.md new file mode 100644 index 0000000..cfcb065 --- /dev/null +++ b/development/ast_graph.md @@ -0,0 +1,419 @@ +# DECNET Codebase AST Graph + +This diagram shows the structural organization of the DECNET project, extracted directly from the Python Abstract Syntax Tree (AST). It includes modules (prefixed with `Module_`), their internal functions, and the classes and methods they contain. + +```mermaid +classDiagram + class Module_distros { + +random_hostname() + +get_distro() + +random_distro() + +all_distros() + } + class distros_DistroProfile { + } + Module_distros ..> distros_DistroProfile : contains + + class custom_service_CustomService { + +__init__() + +compose_fragment() + +dockerfile_context() + } + Module_custom_service ..> custom_service_CustomService : contains + class Module_os_fingerprint { + +get_os_sysctls() + +all_os_families() + } + + class Module_network { + +_run() + +detect_interface() + +detect_subnet() + +get_host_ip() + +allocate_ips() + +create_macvlan_network() + +create_ipvlan_network() + +remove_macvlan_network() + +_require_root() + +setup_host_macvlan() + +teardown_host_macvlan() + +setup_host_ipvlan() + +teardown_host_ipvlan() + +ips_to_range() + } + + class Module_env { + +_port() + +_require_env() + } + + class Module_config { + +random_hostname() + +save_state() + +load_state() + +clear_state() + } + class config_DeckyConfig { + +services_not_empty() + } + Module_config ..> config_DeckyConfig : contains + class config_DecnetConfig { + } + Module_config ..> config_DecnetConfig : contains + class Module_ini_loader { + +load_ini() + +load_ini_from_string() + +validate_ini_string() + +_parse_configparser() + } + class ini_loader_DeckySpec { + } + Module_ini_loader ..> ini_loader_DeckySpec : contains + class ini_loader_CustomServiceSpec { + } + Module_ini_loader ..> ini_loader_CustomServiceSpec : contains + class ini_loader_IniConfig { + } + Module_ini_loader ..> ini_loader_IniConfig : contains + class Module_composer { + +generate_compose() + +write_compose() + } + + class Module_archetypes { + +get_archetype() + +all_archetypes() + +random_archetype() + } + class archetypes_Archetype { + } + Module_archetypes ..> archetypes_Archetype : contains + class Module_fleet { + +all_service_names() + +resolve_distros() + +build_deckies() + +build_deckies_from_ini() + } + + class Module_cli { + +_kill_api() + +api() + +deploy() + +collect() + +mutate() + +status() + +teardown() + +list_services() + +list_distros() + +correlate() + +list_archetypes() + +serve_web() + } + + + class services_base_BaseService { + +compose_fragment() + +dockerfile_context() + } + Module_services_base ..> services_base_BaseService : contains + + class services_http_HTTPService { + +compose_fragment() + +dockerfile_context() + } + Module_services_http ..> services_http_HTTPService : contains + + class services_smtp_SMTPService { + +compose_fragment() + +dockerfile_context() + } + Module_services_smtp ..> services_smtp_SMTPService : contains + + class services_mysql_MySQLService { + +compose_fragment() + +dockerfile_context() + } + Module_services_mysql ..> services_mysql_MySQLService : contains + + class services_redis_RedisService { + +compose_fragment() + +dockerfile_context() + } + Module_services_redis ..> services_redis_RedisService : contains + + class services_elasticsearch_ElasticsearchService { + +compose_fragment() + +dockerfile_context() + } + Module_services_elasticsearch ..> services_elasticsearch_ElasticsearchService : contains + + class services_ftp_FTPService { + +compose_fragment() + +dockerfile_context() + } + Module_services_ftp ..> services_ftp_FTPService : contains + + class services_imap_IMAPService { + +compose_fragment() + +dockerfile_context() + } + Module_services_imap ..> services_imap_IMAPService : contains + + class services_k8s_KubernetesAPIService { + +compose_fragment() + +dockerfile_context() + } + Module_services_k8s ..> services_k8s_KubernetesAPIService : contains + + class services_ldap_LDAPService { + +compose_fragment() + +dockerfile_context() + } + Module_services_ldap ..> services_ldap_LDAPService : contains + + class services_llmnr_LLMNRService { + +compose_fragment() + +dockerfile_context() + } + Module_services_llmnr ..> services_llmnr_LLMNRService : contains + + class services_mongodb_MongoDBService { + +compose_fragment() + +dockerfile_context() + } + Module_services_mongodb ..> services_mongodb_MongoDBService : contains + + class services_mqtt_MQTTService { + +compose_fragment() + +dockerfile_context() + } + Module_services_mqtt ..> services_mqtt_MQTTService : contains + + class services_mssql_MSSQLService { + +compose_fragment() + +dockerfile_context() + } + Module_services_mssql ..> services_mssql_MSSQLService : contains + + class services_pop3_POP3Service { + +compose_fragment() + +dockerfile_context() + } + Module_services_pop3 ..> services_pop3_POP3Service : contains + + class services_postgres_PostgresService { + +compose_fragment() + +dockerfile_context() + } + Module_services_postgres ..> services_postgres_PostgresService : contains + + class services_rdp_RDPService { + +compose_fragment() + +dockerfile_context() + } + Module_services_rdp ..> services_rdp_RDPService : contains + + class services_sip_SIPService { + +compose_fragment() + +dockerfile_context() + } + Module_services_sip ..> services_sip_SIPService : contains + + class services_smb_SMBService { + +compose_fragment() + +dockerfile_context() + } + Module_services_smb ..> services_smb_SMBService : contains + + class services_snmp_SNMPService { + +compose_fragment() + +dockerfile_context() + } + Module_services_snmp ..> services_snmp_SNMPService : contains + + class services_tftp_TFTPService { + +compose_fragment() + +dockerfile_context() + } + Module_services_tftp ..> services_tftp_TFTPService : contains + + class services_vnc_VNCService { + +compose_fragment() + +dockerfile_context() + } + Module_services_vnc ..> services_vnc_VNCService : contains + + class services_docker_api_DockerAPIService { + +compose_fragment() + +dockerfile_context() + } + Module_services_docker_api ..> services_docker_api_DockerAPIService : contains + class Module_services_registry { + +_load_plugins() + +register_custom_service() + +get_service() + +all_services() + } + + + class services_smtp_relay_SMTPRelayService { + +compose_fragment() + +dockerfile_context() + } + Module_services_smtp_relay ..> services_smtp_relay_SMTPRelayService : contains + + class services_conpot_ConpotService { + +compose_fragment() + +dockerfile_context() + } + Module_services_conpot ..> services_conpot_ConpotService : contains + + class services_ssh_SSHService { + +compose_fragment() + +dockerfile_context() + } + Module_services_ssh ..> services_ssh_SSHService : contains + + class services_telnet_TelnetService { + +compose_fragment() + +dockerfile_context() + } + Module_services_telnet ..> services_telnet_TelnetService : contains + class Module_logging_forwarder { + +parse_log_target() + +probe_log_target() + } + + class Module_logging_file_handler { + +_get_logger() + +write_syslog() + +get_log_path() + } + + class Module_logging_syslog_formatter { + +_pri() + +_truncate() + +_sd_escape() + +_sd_element() + +format_rfc5424() + } + + + class correlation_graph_TraversalHop { + } + Module_correlation_graph ..> correlation_graph_TraversalHop : contains + class correlation_graph_AttackerTraversal { + +first_seen() + +last_seen() + +duration_seconds() + +deckies() + +decky_count() + +path() + +to_dict() + } + Module_correlation_graph ..> correlation_graph_AttackerTraversal : contains + class Module_correlation_engine { + +_fmt_duration() + } + class correlation_engine_CorrelationEngine { + +__init__() + +ingest() + +ingest_file() + +traversals() + +all_attackers() + +report_table() + +report_json() + +traversal_syslog_lines() + } + Module_correlation_engine ..> correlation_engine_CorrelationEngine : contains + class Module_correlation_parser { + +_parse_sd_params() + +_extract_attacker_ip() + +parse_line() + } + class correlation_parser_LogEvent { + } + Module_correlation_parser ..> correlation_parser_LogEvent : contains + class Module_web_auth { + +verify_password() + +get_password_hash() + +create_access_token() + } + + class Module_engine_deployer { + +_sync_logging_helper() + +_compose() + +_compose_with_retry() + +deploy() + +teardown() + +status() + +_print_status() + } + + class Module_collector_worker { + +parse_rfc5424() + +_load_service_container_names() + +is_service_container() + +is_service_event() + +_stream_container() + } + + class Module_mutator_engine { + +mutate_decky() + +mutate_all() + +run_watch_loop() + } + + + class web_db_repository_BaseRepository { + } + Module_web_db_repository ..> web_db_repository_BaseRepository : contains + + class web_db_models_User { + } + Module_web_db_models ..> web_db_models_User : contains + class web_db_models_Log { + } + Module_web_db_models ..> web_db_models_Log : contains + class web_db_models_Bounty { + } + Module_web_db_models ..> web_db_models_Bounty : contains + class web_db_models_Token { + } + Module_web_db_models ..> web_db_models_Token : contains + class web_db_models_LoginRequest { + } + Module_web_db_models ..> web_db_models_LoginRequest : contains + class web_db_models_ChangePasswordRequest { + } + Module_web_db_models ..> web_db_models_ChangePasswordRequest : contains + class web_db_models_LogsResponse { + } + Module_web_db_models ..> web_db_models_LogsResponse : contains + class web_db_models_BountyResponse { + } + Module_web_db_models ..> web_db_models_BountyResponse : contains + class web_db_models_StatsResponse { + } + Module_web_db_models ..> web_db_models_StatsResponse : contains + class web_db_models_MutateIntervalRequest { + } + Module_web_db_models ..> web_db_models_MutateIntervalRequest : contains + class web_db_models_DeployIniRequest { + } + Module_web_db_models ..> web_db_models_DeployIniRequest : contains + class Module_web_db_sqlite_database { + +get_async_engine() + +get_sync_engine() + +init_db() + } + + + class web_db_sqlite_repository_SQLiteRepository { + +__init__() + +_initialize_sync() + +_apply_filters() + +_apply_bounty_filters() + } + Module_web_db_sqlite_repository ..> web_db_sqlite_repository_SQLiteRepository : contains +``` diff --git a/development/complete_execution_graph.md b/development/complete_execution_graph.md new file mode 100644 index 0000000..21aa92b --- /dev/null +++ b/development/complete_execution_graph.md @@ -0,0 +1,192 @@ +# DECNET: Complete Execution Graph + +This diagram represents the absolute complete call graph of the DECNET project. It connects initial entry points (CLI and Web API) through the orchestration layers, down to the low-level network and service container logic. + +```mermaid +graph TD + subgraph CLI_Entry + cli__kill_api([_kill_api]) + cli_api([api]) + cli_deploy([deploy]) + cli_collect([collect]) + cli_mutate([mutate]) + cli_status([status]) + cli_teardown([teardown]) + cli_list_services([list_services]) + cli_list_distros([list_distros]) + cli_correlate([correlate]) + cli_list_archetypes([list_archetypes]) + cli_serve_web([serve_web]) + cli_do_GET([do_GET]) + end + subgraph Fleet_Management + distros_random_hostname([distros_random_hostname]) + distros_get_distro([distros_get_distro]) + distros_random_distro([distros_random_distro]) + distros_all_distros([distros_all_distros]) + ini_loader_load_ini([ini_loader_load_ini]) + ini_loader_load_ini_from_string([ini_loader_load_ini_from_string]) + ini_loader_validate_ini_string([ini_loader_validate_ini_string]) + ini_loader__parse_configparser([ini_loader__parse_configparser]) + archetypes_get_archetype([archetypes_get_archetype]) + archetypes_all_archetypes([archetypes_all_archetypes]) + archetypes_random_archetype([archetypes_random_archetype]) + fleet_all_service_names([all_service_names]) + fleet_resolve_distros([resolve_distros]) + fleet_build_deckies([build_deckies]) + fleet_build_deckies_from_ini([build_deckies_from_ini]) + end + subgraph Deployment_Engine + network__run([network__run]) + network_detect_interface([network_detect_interface]) + network_detect_subnet([network_detect_subnet]) + network_get_host_ip([network_get_host_ip]) + network_allocate_ips([network_allocate_ips]) + network_create_macvlan_network([network_create_macvlan_network]) + network_create_ipvlan_network([network_create_ipvlan_network]) + network_remove_macvlan_network([network_remove_macvlan_network]) + network__require_root([network__require_root]) + network_setup_host_macvlan([network_setup_host_macvlan]) + network_teardown_host_macvlan([network_teardown_host_macvlan]) + network_setup_host_ipvlan([network_setup_host_ipvlan]) + network_teardown_host_ipvlan([network_teardown_host_ipvlan]) + network_ips_to_range([network_ips_to_range]) + config_random_hostname([config_random_hostname]) + config_save_state([config_save_state]) + config_load_state([config_load_state]) + config_clear_state([config_clear_state]) + composer_generate_compose([composer_generate_compose]) + composer_write_compose([composer_write_compose]) + engine_deployer__sync_logging_helper([_sync_logging_helper]) + engine_deployer__compose([_compose]) + engine_deployer__compose_with_retry([_compose_with_retry]) + engine_deployer_deploy([deploy]) + engine_deployer_teardown([teardown]) + engine_deployer_status([status]) + engine_deployer__print_status([_print_status]) + end + subgraph Monitoring_Mutation + collector_worker_parse_rfc5424([parse_rfc5424]) + collector_worker__load_service_container_names([_load_service_container_names]) + collector_worker_is_service_container([is_service_container]) + collector_worker_is_service_event([is_service_event]) + collector_worker__stream_container([_stream_container]) + collector_worker_log_collector_worker([log_collector_worker]) + collector_worker__spawn([_spawn]) + collector_worker__watch_events([_watch_events]) + mutator_engine_mutate_decky([mutate_decky]) + mutator_engine_mutate_all([mutate_all]) + mutator_engine_run_watch_loop([run_watch_loop]) + end + subgraph Web_Service + web_auth_verify_password([web_auth_verify_password]) + web_auth_get_password_hash([web_auth_get_password_hash]) + web_auth_create_access_token([web_auth_create_access_token]) + web_db_repository_initialize([web_db_repository_initialize]) + web_db_repository_add_log([web_db_repository_add_log]) + web_db_repository_get_logs([web_db_repository_get_logs]) + web_db_repository_get_total_logs([web_db_repository_get_total_logs]) + web_db_repository_get_stats_summary([web_db_repository_get_stats_summary]) + web_db_repository_get_deckies([web_db_repository_get_deckies]) + web_db_repository_get_user_by_uuid([web_db_repository_get_user_by_uuid]) + web_db_repository_update_user_password([web_db_repository_update_user_password]) + web_db_repository_add_bounty([web_db_repository_add_bounty]) + web_db_repository_get_bounties([web_db_repository_get_bounties]) + web_db_repository_get_total_bounties([web_db_repository_get_total_bounties]) + web_db_sqlite_database_get_async_engine([web_db_sqlite_database_get_async_engine]) + web_db_sqlite_database_get_sync_engine([web_db_sqlite_database_get_sync_engine]) + web_db_sqlite_database_init_db([web_db_sqlite_database_init_db]) + web_db_sqlite_repository_initialize([web_db_sqlite_repository_initialize]) + web_db_sqlite_repository_reinitialize([web_db_sqlite_repository_reinitialize]) + web_db_sqlite_repository_add_log([web_db_sqlite_repository_add_log]) + web_db_sqlite_repository__apply_filters([web_db_sqlite_repository__apply_filters]) + web_db_sqlite_repository_get_logs([web_db_sqlite_repository_get_logs]) + web_db_sqlite_repository_get_max_log_id([web_db_sqlite_repository_get_max_log_id]) + web_db_sqlite_repository_get_logs_after_id([web_db_sqlite_repository_get_logs_after_id]) + web_db_sqlite_repository_get_total_logs([web_db_sqlite_repository_get_total_logs]) + web_db_sqlite_repository_get_log_histogram([web_db_sqlite_repository_get_log_histogram]) + web_db_sqlite_repository_get_stats_summary([web_db_sqlite_repository_get_stats_summary]) + web_db_sqlite_repository_get_deckies([web_db_sqlite_repository_get_deckies]) + web_db_sqlite_repository_get_user_by_username([web_db_sqlite_repository_get_user_by_username]) + web_db_sqlite_repository_get_user_by_uuid([web_db_sqlite_repository_get_user_by_uuid]) + web_db_sqlite_repository_create_user([web_db_sqlite_repository_create_user]) + web_db_sqlite_repository_update_user_password([web_db_sqlite_repository_update_user_password]) + web_db_sqlite_repository_add_bounty([web_db_sqlite_repository_add_bounty]) + web_db_sqlite_repository__apply_bounty_filters([web_db_sqlite_repository__apply_bounty_filters]) + web_db_sqlite_repository_get_bounties([web_db_sqlite_repository_get_bounties]) + web_db_sqlite_repository_get_total_bounties([web_db_sqlite_repository_get_total_bounties]) + web_router_auth_api_change_pass_change_password([auth_api_change_pass_change_password]) + web_router_auth_api_login_login([auth_api_login_login]) + web_router_logs_api_get_logs_get_logs([logs_api_get_logs_get_logs]) + web_router_logs_api_get_histogram_get_logs_histogram([logs_api_get_histogram_get_logs_histogram]) + web_router_bounty_api_get_bounties_get_bounties([bounty_api_get_bounties_get_bounties]) + web_router_stats_api_get_stats_get_stats([stats_api_get_stats_get_stats]) + web_router_fleet_api_mutate_decky_api_mutate_decky([api_mutate_decky_api_mutate_decky]) + web_router_fleet_api_get_deckies_get_deckies([api_get_deckies_get_deckies]) + web_router_fleet_api_mutate_interval_api_update_mutate_interval([api_mutate_interval_api_update_mutate_interval]) + web_router_fleet_api_deploy_deckies_api_deploy_deckies([api_deploy_deckies_api_deploy_deckies]) + web_router_stream_api_stream_events_stream_events([stream_api_stream_events_stream_events]) + web_router_stream_api_stream_events_event_generator([stream_api_stream_events_event_generator]) + end + + %% Key Connection Edges + network_detect_interface --> network__run + network_detect_subnet --> network__run + network_get_host_ip --> network__run + network_setup_host_macvlan --> network__run + network_teardown_host_macvlan --> network__run + network_setup_host_ipvlan --> network__run + network_teardown_host_ipvlan --> network__run + + ini_loader_load_ini --> ini_loader__parse_configparser + ini_loader_load_ini_from_string --> ini_loader__parse_configparser + + composer_generate_compose --> os_fingerprint_get_os_sysctls + composer_write_compose --> composer_generate_compose + + fleet_resolve_distros --> distros_random_distro + fleet_build_deckies --> fleet_resolve_distros + fleet_build_deckies --> config_random_hostname + fleet_build_deckies_from_ini --> archetypes_get_archetype + fleet_build_deckies_from_ini --> fleet_all_service_names + + cli_deploy --> ini_loader_load_ini + cli_deploy --> network_detect_interface + cli_deploy --> fleet_build_deckies_from_ini + cli_deploy --> engine_deployer_deploy + + cli_collect --> collector_worker_log_collector_worker + cli_mutate --> mutator_engine_run_watch_loop + + cli_correlate --> correlation_engine_ingest_file + cli_correlate --> correlation_engine_traversals + + engine_deployer_deploy --> network_ips_to_range + engine_deployer_deploy --> network_setup_host_macvlan + engine_deployer_deploy --> composer_write_compose + engine_deployer_deploy --> engine_deployer__compose_with_retry + + engine_deployer_teardown --> network_teardown_host_macvlan + engine_deployer_teardown --> config_clear_state + + collector_worker_log_collector_worker --> collector_worker__stream_container + collector_worker__stream_container --> collector_worker_parse_rfc5424 + + mutator_engine_mutate_decky --> composer_write_compose + mutator_engine_mutate_decky --> engine_deployer__compose_with_retry + mutator_engine_mutate_all --> mutator_engine_mutate_decky + mutator_engine_run_watch_loop --> mutator_engine_mutate_all + + web_db_sqlite_repository_initialize --> web_db_sqlite_database_init_db + web_db_sqlite_repository_get_logs --> web_db_sqlite_repository__apply_filters + + web_router_auth_api_login_login --> web_auth_verify_password + web_router_auth_api_login_login --> web_auth_create_access_token + + web_router_logs_api_get_logs_get_logs --> web_db_sqlite_repository_get_logs + web_router_fleet_api_mutate_decky_api_mutate_decky --> mutator_engine_mutate_decky + web_router_fleet_api_deploy_deckies_api_deploy_deckies --> fleet_build_deckies_from_ini + + web_router_stream_api_stream_events_stream_events --> web_db_sqlite_repository_get_logs_after_id + web_router_stream_api_stream_events_stream_events --> web_router_stream_api_stream_events_event_generator +``` diff --git a/development/execution_graphs.md b/development/execution_graphs.md new file mode 100644 index 0000000..e817f3e --- /dev/null +++ b/development/execution_graphs.md @@ -0,0 +1,66 @@ +# DECNET Execution Graphs + +These graphs illustrate the logical flow of execution within the DECNET framework, showing how high-level commands and API requests trigger secondary processes and subsystem interactions. + +## 1. Deployment & Teardown Flow +This flow shows the orchestration from a CLI `deploy` command down to network setup and container instantiation. + +```mermaid +graph TD + CLI_Deploy([cli.deploy]) --> INI[ini_loader.load_ini] + CLI_Deploy --> NET_Detect[network.detect_interface] + CLI_Deploy --> FleetBuild[fleet.build_deckies_from_ini] + + FleetBuild --> Archetype[archetypes.get_archetype] + FleetBuild --> Distro[distros.get_distro] + + CLI_Deploy --> Engine_Deploy[engine.deployer.deploy] + + Engine_Deploy --> IP_Alloc[network.allocate_ips] + Engine_Deploy --> NET_Setup[network.setup_host_macvlan] + Engine_Deploy --> Compose_Gen[composer.write_compose] + Engine_Deploy --> Docker_Up[engine.deployer._compose_with_retry] + + CLI_Teardown([cli.teardown]) --> Engine_Teardown[engine.deployer.teardown] + Engine_Teardown --> NET_Cleanup[network.teardown_host_macvlan] + Engine_Teardown --> Docker_Down[engine.deployer._compose] +``` + +## 2. Mutation & Monitoring Flow +How DECNET maintains deception by periodically changing decoy identities and monitoring activities. + +```mermaid +graph LR + subgraph Periodic_Process + CLI_Mutate([cli.mutate]) --> Mutate_Loop[mutator.engine.run_watch_loop] + end + + Mutate_Loop --> Mutate_All[mutator.engine.mutate_all] + Mutate_All --> Mutate_Decky[mutator.engine.mutate_decky] + + Mutate_Decky --> Get_New_Identity[archetypes.get_archetype] + Mutate_Decky --> Rewrite_Compose[composer.write_compose] + Mutate_Decky --> Restart_Container[engine.deployer._compose_with_retry] + + subgraph Log_Collection + CLI_Collect([cli.collect]) --> Worker[collector.worker.log_collector_worker] + Worker --> Stream[collector.worker._stream_container] + Stream --> Parse[collector.worker.parse_rfc5424] + end +``` + +## 3. Web API Flow (Fleet Management) +How the Web UI interacts with the underlying systems via the FastAPI router. + +```mermaid +graph TD + Web_UI[Web Dashboard] --> API_Deploy[web.router.fleet.deploy_deckies] + Web_UI --> API_Mutate[web.router.fleet.mutate_decky] + Web_UI --> API_Stream[web.router.stream.stream_events] + + API_Deploy --> FleetBuild[fleet.build_deckies_from_ini] + API_Mutate --> Mutator[mutator.engine.mutate_decky] + + API_Stream --> DB_Pull[web.db.sqlite.repository.get_logs_after_id] + DB_Pull --> SQLite[(SQLite Database)] +```