Archon One

Core Scanning & Metrics

Accurate line counts (Physical, Logical, Blank, Comment), character counts, and stateful comment extraction rules for different syntaxes.

Security Checker

Detects committed private keys, AWS tokens, hardcoded IP configurations, weak cryptographic hashing, dangerous function execution (like eval), hardcoded Authorization headers/tokens, and XML External Entity (XXE) vulnerabilities.

Code Analysis & Smells

Finds structural smells like God Functions, Lazy Classes, Message Chains, Empty catch/except blocks, Empty Classes, and Deep Nesting logic.

Git Intelligence & Ownership

Calculates ownership distributions, commit activity, bus factors, risk areas, and developer activity statistics directly from local git transaction history.

Unified Reports

Saves individual text/JSON files per category, and consolidates them into a single interactive HTML file.

From PyPI

Install the production-ready package directly using pip:

pip install archon-one

From Source (Development Setup)

To run Archon One in development mode, clone the repository and install dependencies:

git clone https://github.com/v3ravani/Archon-One
cd Archon-One
pip install -e ".[dev]"

Troubleshooting

Ensure that git is installed on your command path to allow contributor and commit analysis. On Windows, if python command mapping fails, check environment path variables.

1. Run scan: Run scan on the current directory:

   archon scan

2. Review outputs: The report files will be saved in the archon-one/ directory with a sub-folder matching the scan timestamp.

3. Configure settings: Start the settings server to modify rule thresholds:

   archon settings

4. Scan Remote Repository: Clone and scan a remote GitHub repository directly:

   archon git https://github.com/v3ravani/HogwartsHackademy

Pipeline Workflow

Module Relationship Mapping

{
  "general": {
    "project_name": "Archon One Project",
    "output_folder": "archon-one",
    "create_timestamp_folder": true
  },
  "modules": {
    "code_metrics": true,
    "security": true,
    "code_analysis": true,
    "contributor_analysis": true,
    "repository_intelligence": true,
    "knowledge_graph": true
  },
  "knowledge_graph": {
    "include_classes": true,
    "include_functions": true,
    "include_dependencies": true,
    "include_apis": true,
    "include_database": true,
    "include_configurations": true,
    "max_depth": 10,
    "min_node_connections": 1
  },
  "ignore_rules": {
    "ignore_directories": [
      "node_modules",
      ".git",
      "venv",
      "build",
      "dist",
      "coverage"
    ],
    "ignore_files": [
      "*.min.js",
      "*.min.css"
    ],
    "ignore_extensions": [
      "png",
      "jpg",
      "ico"
    ]
  }
}

Key Metrics & Formulas

• Physical Lines of Code (PLOC): Total file newline counts.
• Logical Lines of Code (LLOC): Lines containing active statements, excluding blank lines and pure comments.
• Comment Density: (Comment Lines / Total Lines) * 100. Density below 10% triggers warnings.

Monitored Code Smells

• God Function: Functions whose LOC/complexity index exceeds clean code thresholds.
• Empty Classes: Dead stub configurations containing zero active attributes or method overrides.
• Deep Nesting: Conditional block depth exceeding settings limits (e.g., nesting depth > 4).

Key Insights

• Bus Factor: Minimum number of engineers whose departure stops progress (based on file ownership).
• Knowledge Silos: Files where a single author has written over 80% of lines.
• Commit Velocity: Traces modifications, deletions, and active commits over time.

Grade Map

Features

• Graph Nodes: Automatically discover and create nodes for classes, functions, DB models, API endpoints, etc.
• Relationships Mapping: Map code calls, imports, inheritance, exceptions, and environment configurations.
• Customization Toggles: Filter nodes, relations, classes, databases, API definitions, environment configuration files, or limit traversal depth.

Knowledge Graph Customizations

The Knowledge Graph generation can be fully customized using configuration parameters under the knowledge_graph section in the settings panel or archon-config.json:

Option Key	Type	Default	Description
include_classes	Boolean	true	Include classes, interfaces, enums, and structs.
include_functions	Boolean	true	Include standalone functions, methods, and constructors.
include_dependencies	Boolean	true	Include package/module imports and dependency chains.
include_apis	Boolean	true	Include web API route definitions and endpoint controllers.
include_database	Boolean	true	Include database tables, models, and query linkages.
include_configurations	Boolean	true	Include environment variables, config files, and feature flags.
max_depth	Integer	10	BFS traversal depth limit to cap relationship exploration.
min_node_connections	Integer	1	Skip/prune nodes with connection degree below this value.

Available Diagrams

• Overall Repository Architecture: High-level entry points, core subsystems, and modular boundaries mapping.
• Component Diagram: Shows Controllers, CLI layers, Service logic, Repositories, Databases, and configuration structures.
• Module Diagram: Maps logical components and inter-module dependencies.
• Package Diagram: Displays directory package layout and their relationships.
• Dependency Diagram: Highlights internal import paths, external modules, circular imports (red), and shared helpers (green).
• Folder Structure: Tree structure of the repository directories.
• Service Flow Diagram: Scans runtime request flows and processing steps.
• Function Call Graph: Maps calls between functions across the codebase.
• Data Flow Diagram: Maps input data streams, processing systems, and report generation engines.
• Class Relationship Diagram: Focuses on classes inheritance structure and property bindings.
• Sequence Diagram: Shows scan CLI execution sequences.
• State Diagram: Lifecycle state transitions of scanner processing steps.
• Entity Relationship Diagram: Relates code model constructs.
• Security Diagram: Displays scan execution security check trust boundaries.

Settings parameters

Option Key	Type	Default	Description
include_mmd	Boolean	true	Write `.mmd` Mermaid source files.
include_puml	Boolean	true	Write `.puml` PlantUML source files.
max_nodes	Integer	50	Limits scanned node count rendering inside dependency diagrams.

archon-one/
└── 2026-07-10_20-55-05/
    ├── 01_metrics/
    │   ├── 01_repository_summary.txt
    │   ├── 02_file_metrics.txt
    │   └── 03_language_distribution.txt
    ├── 02_security/
    │   ├── 01_security_summary.txt
    │   └── 02_vulnerabilities.txt
    ├── 03_Code_Analysis/
    │   └── 01_complexity_report.txt
    ├── 04_Contributor_Analysis/
    │   └── 01_git_history.txt
    ├── 05_Repository_Intelligence/
    │   └── 01_health_rating.txt
    ├── 06_knowledge_graph/
    │   ├── graph_summary.txt
    │   ├── graph_summary.json
    │   └── repository_map.md
    └── index.html (Unified Interactive HTML Report)

• Tabbed Navigation: Quickly switch between Code Metrics, Security findings, Contributor stats, and Health grades.
• Live Searching & Filtering: Instantly search table records by file names, rule categories, or severity.
• Data Exporting: Includes actions to download tables directly to CSV or print clean copy sheets.
• Offline Dependency: Every report compiles inline CSS and JS, running entirely offline.

$ archon scan
[*] Scan progress: [====================] 100.0% (26/26)
[*] Generating metrics reports...
[*] Generating security reports...
[*] Generating code analysis reports...
[*] Generating contributor analysis reports...
[*] Generating repository intelligence reports...
[*] Finalizing scan and saving reports...

==================================================
               SCAN SUMMARY
==================================================
Total Files Found   31
Files Scanned       19
Files Ignored       12
Total Size Scanned  624.86 KB
Scan Duration       1.007 seconds
==================================================
[+] Reports saved to:
   C:\Users\ravan\Desktop\archonone\archon-one\2026-07-10_20-59-13
==================================================

• Optimized File System Traversal: Scans only supported file extensions, bypassing heavy media and dependency files.
• Fast Regex Compilations: All security match rules compile prior to line scans to accelerate pattern checking.
• Sub-Second Execution: Typical repositories under 500 files scan in less than 1.0 second.

1. What is Archon One?

Archon One is a client-side command line code analysis, security auditing, and repository intelligence platform that executes audits completely offline.

2. Does Archon One upload my source code to any cloud servers?

No. All scans, regex pattern matches, and report generation routines are executed locally on your machine. No data is transmitted to external servers.

3. What is the difference between Archon One and standard analyzers?

Standard tools usually require online integrations and upload files to their servers. Archon One guarantees 100% offline security, compiling full reports (including interactive HTML interfaces) locally.

4. What are the installation requirements?

You need Python >= 3.11 and the Git command line utility installed and available in your environment path.

5. How do I install Archon One via pip?

Simply run pip install archon-one.

6. How can I run a scan on a directory?

Run archon scan to scan the current directory, or specify a path: archon scan /path/to/project.

7. How do I scan a remote repository?

Use the git command: archon git https://github.com/v3ravani/HogwartsHackademy. It will clone, analyze, generate reports locally, and safely clean up the temporary workspace files.

8. How do I customize settings?

Run archon settings to launch the interactive browser configuration editor locally, or edit the archon-config.json file in your workspace directory manually.

9. What is the "Code Health Index"?

It is an aggregated score out of 100 calculated by combining metrics, security violations, complexity findings, and repository history to represent overall code quality.

10. What is "Bus Factor"?

A metric indicating the distribution risk of a repository, representing the minimum number of authors who own over 80% of files.

11. Why do I get a permission error on Windows when using the git scan command?

On Windows, Git files inside the `.git` directory may write read-only permissions. The tool has been updated to override file access locks, clear the read-only attribute, and retry the directory cleanup safely.

12. How do I disable a specific analysis module?

Toggle the target module Boolean value (e.g. "security": false) under the "modules" section inside the local archon-config.json configuration file.

13. Where are generated scan reports saved?

By default, they are output to the archon-one/ directory inside your current working directory, organized into sub-folders by scan timestamp.

14. Does Archon One support JSON exports?

Yes. Every report generated is output as text tables, JSON data payloads, and Markdown files.

15. What security checks are currently built in?

It checks for hardcoded credentials (AWS, SSH keys), weak cryptography usage (MD5), insecure functions (eval), XXE parser vulnerabilities, and exposed Bearer authorization tokens.

16. Can I run scans on code bases that aren't Git repositories?

Yes, but contributor analysis metrics (Module 04) will be skipped as they rely on git transaction logs. Other modules (Metrics, Security, Code Analysis) will execute normally.

17. Does the tool support file and folder ignore rules?

Yes. You can customize ignored extensions, ignore specific files, or skip entire directories (e.g. node_modules) using settings.

18. How do I reset settings to defaults?

Execute archon config reset to reset settings back to default parameters.

19. Can I customize the output folder path?

Yes, use the -o or --output CLI option flag during execution to output reports to any custom folder path.

20. What is a "God Function"?

A code smell flagged when a function's length or nesting complexity score exceeds threshold settings.

21. What is the Knowledge Graph module?

Module 06 constructs a structured representation of the codebase. It statically parses imports, calls, classes, functions, configurations, and database schemas to map how different code files and modules interact, saving the topological data as JSON and MD reports.

22. How is comment density evaluated?

It calculates the ratio of comment lines to total logical lines of code. Densities below 10% raise code smell warnings.

23. What is an XXE vulnerability check?

It flags imports of standard Python XML parsers (e.g. xml.etree) when they are loaded without explicitly disabling external entity references, or when defusedxml is not used.

23. What is the difference between sdist and wheel formats?

An sdist (source distribution) contains raw package source files, while a wheel is a compiled binary package. Archon One builds both distribution formats successfully.

24. Does the interactive HTML report require an internet connection to run?

No. All CSS layouts, Javascript behaviors, and tabular search functions are compiled directly inline. The file runs entirely offline.

25. Can I use Archon One in CI/CD pipeline runs?

Yes. The tool returns standard shell exit codes (0 for success, 1 for errors) making it easy to integrate into build workflows.

26. What Python versions are supported?

Archon One is optimized for Python 3.11, 3.12, 3.13, and 3.14.

27. How does it handle large files?

Files exceeding the configured file size limit (e.g. 10MB) are automatically ignored during scanning to optimize speed and resource consumption.

28. Is there a command to check the installed package version?

Yes, run archon --version or archon -v.

29. Can I contribute to Archon One?

Yes, contributions are welcome. Fork the repository on GitHub and open a pull request with unit test coverage.

30. What license does Archon One use?

Archon One is open-source software licensed under the terms of the MIT License.

• Trend Analytics: Add historical scan aggregation to graph metric changes over time.
• Enhanced Language ASTs: Integrate detailed syntax tree evaluations for JavaScript and TypeScript.
• CI/CD Reporter Extensions: Export raw JUnit XML and GitHub action log tables natively.

1. Fork the repository: github.com/v3ravani/Archon-One.
2. Create a branch for your feature or bug fix: git checkout -b feature/cool-new-rule.
3. Add test cases under the tests/ directory and verify with pytest.
4. Open a Pull Request with details on changes and verify package compliance.

Copyright (c) 2026 Viraj Ravani. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files to use, modify, merge, publish, or distribute packages without limitations.