Specification

Argos is a high-assurance File Integrity Monitoring (FIM) system designed for security-critical environments. It employs cryptographic hash chaining and behavioral analysis to detect, classify, and explain unauthorized modifications to the filesystem perimeter.

Quick Start

01. Initialize the Baseline

Establish the "Known-Good" state of your target directory.

$
argos init /path/to/project --name v1.0

02. Continuous Monitoring

Initiate the Watch engine to detect real-time drifts.

$
argos watch /path/to/project

03. Audit and Explain

Perform a deep-audit with AI-assisted classification of anomalies.

$
argos check /path/to/project --explain

Architecture Overview

Argos operates on a stateless-scan/stateful-comparison model. The system establishes a "Baseline" by computing immutable fingerprints for all target assets.

Operation Pipeline

01

Baseline Initialization

Recursive traversal of the target directory to establish cryptographic and behavioral identity.

02

Snapshot Comparison

Delta analysis between the active state and a stored baseline.

03

Semantic Inspection

Deep analysis of code structural changes using Abstract Syntax Trees (AST).

04

Behavioral Classification

Heuristic evaluation of changes to determine intent and risk.

05

Ledger Append

Recording the event in an append-only, cryptographically chained audit log.

Technical Specifications

Cryptographic Foundation

Argos supports SHA-256 and SHA-512 algorithms for content hashing. The selection is configurable based on the required collision resistance and performance profiles of the target environment.

Tamper-Evident Ledger

The audit log (Ledger) is implemented as a hash chain. Each entry N contains a hash of its own data concatenated with the hash of entry N − 1. This ensures that any modification of the audit history results in a detectable break.

Installation and Deployment

Requirements

  • • Python 3.8 or higher
  • • SQLite 3.x

Standard Installation

bash
pip install git+https://github.com/Z35Tyyyy/Argos.git

Recommended (Isolated Environment)

01. Initialize Environment

terminal
python -m venv venv

02. Activation

PowerShell.\venv\Scripts\Activate.ps1
Bash/Zshsource venv/bin/activate

03. Local Installation

terminal
pip install .

Global Configuration

Groq AI Integration

To enable the AI-assisted explanation feature (--explain), provide a valid Groq API key in the GROQ_API_KEY environment variable.

Windows (PS)
$env:GROQ_API_KEY = "your_api_key_here"
Unix/macOS
export GROQ_API_KEY="your_api_key_here"

Persistent Setup (Windows)

  1. 1. Search for **Environment Variables** in the Start Menu.
  2. 2. Under "User variables", click **New**.
  3. 3. Variable name: GROQ_API_KEY
  4. 4. Variable value: Paste your key from [console.groq.com](https://console.groq.com)

Command Line Interface

Phase 01: Provisioning

argos init [DIRECTORY]

Command Reference

Use this to establish the initial 'Known-Good' state of a project. It recursively fingerprints every asset into a cryptographically signed baseline.

Pro-Tip: Use '--algo sha512' for high-assurance environments requiring maximum collision resistance.

Options & Flags
--name [NAME]

Identifier for the baseline. Allows tracking multiple versions (e.g., v1.0, v2.0).

--algo [sha256|sha512]

Selects the content hashing algorithm (default: sha256).

--db [PATH]

Explicitly path the SQLite baseline database for remote storage.

Usage Sample
cmd
$
argos init ./src --name release-v1 --algo sha512

argos update [DIRECTORY]

Command Reference

Promote the current filesystem state to the baseline. Intended for use after authorized deployments or system updates.

Warning: This operation effectively 'forgets' previous drifts. Ensure all modifications are authorized before updating.

Options & Flags
--baseline [NAME]

Specifies which baseline identifier to update.

--db [PATH]

Path to the SQLite baseline database.

Usage Sample
cmd
$
argos update ./src --baseline release-v1

Phase 02: Active Surveillance

argos check [DIRECTORY]

Command Reference

Performs a high-speed delta analysis between the active filesystem and a stored baseline to identify unauthorized drifts.

Combined with '--explain', Argos uses LLM-assisted structural analysis to tell you exactly HOW a script changed.

Options & Flags
--baseline [NAME]

Select the specific snapshot to compare against.

--explain

Enables AI-assisted semantic analysis of modifications (Requires GROQ_API_KEY).

--output [format]

Serialization format: terminal, json, csv, or html.

Usage Sample
cmd
$
argos check ./src --explain --output json

argos watch [DIRECTORY]

Command Reference

Initiates continuous monitoring mode. Ideal for production servers where real-time detection of filesystem tampering is critical.

Default interval is 60 seconds. Adjust for lower latency or higher performance footprints.

Options & Flags
--interval [SECONDS]

Frequency of recursive scans (default: 60).

--explain

Enable real-time AI classification of detected drifts.

--db [PATH]

Path to the SQLite baseline database.

Usage Sample
cmd
$
argos watch ./src --interval 30 --explain

Phase 03: Chain Verification

argos report

Command Reference

Displays the historical audit ledger. Every detection event is recorded in a cryptographically chained log.

Options & Flags
--since [TIMESTAMP]

Filter ledger entries by ISO timestamp (e.g., 2024-01-01).

--format [format]

Report serialization: terminal, json, or html.

Usage Sample
cmd
$
argos report --since 2024-04-10

argos verify-chain

Command Reference

Performs a full cryptographic validation of the audit ledger. Ensures that no historical monitoring events have been tampered with.

This is the Mathematical Proof of Audit Trail Integrity.

Options & Flags
--db [PATH]

Path to the SQLite database containing the ledger chain.

Usage Sample
cmd
$
argos verify-chain --db ./audit.db

Intelligent Classification

CRITICALRisk Level: High

High probability of malicious intent or severe system instability.

  • System Perimeter Breach: Modifications within protected directories.
  • Executable Entropy Drift: Changes to binaries or executable scripts.
  • Risky Logic Injections: Addition of dynamic execution calls (exec, eval).
  • Ransomware Indicators: Entropy shifts exceeding 2.0.
SUSPICIOUSRisk Level: Medium

Unusual behavior requiring manual audit.

  • Credential/Secret Access: Keywords like 'token', 'key', or 'password'.
  • Network Capability Addition: Import of networking modules.
  • Subtle Obfuscation: Entropy shifts between 1.0 and 2.0.
ROUTINERisk Level: Low

Standard maintenance or non-security refactoring.

  • Documentation Updates: Changes to .md, .txt, or comment blocks.
  • Asset Formatting: Non-functional changes (indentation, styling).

Behavioral Fingerprinting

Shannon Entropy

Argos measures the randomness of file data to detect encrypted payloads. 0.0-4.0 for source code/text; 6.0-8.0 for compressed/encrypted data.

AST-Based Logic

For Python assets, the ast module performs non-textual diffing, distinguishing harmless formatting from functional logic shifts.

System Configuration

.argos.yml

yaml
algorithm: sha512
exclude_patterns:
  - "logs/*"
  - "*.tmp"
watch_interval: 30

.argosignore

text
node_modules/
venv/
*.log

Audit Ledger Integrity

Argos provides a mathematical guarantee of audit trail continuity. Use the verify-chain command to ensure historical record integrity.

License

Distributed under the MIT License. See LICENSE for details.