Advanced

A deep dive into Falcn’s architecture, from high-level system design to individual component interactions.

System Overview

Falcn is built as a modular, pipeline-based security scanner designed for high throughput and extensibility. The architecture separates concerns between input parsing, detection algorithms, AI analysis, and output generation.

High-Level Architecture

Figure 1: Falcn processes packages through multiple detection layers before generating outputs

Core Components

📥 Input Layer

Accepts requests from CLI, REST API, or CI/CD webhooks. Normalizes input into a standard PackageRequest format regardless of source.

⚙️ Core Engine

Orchestrates the scanning pipeline. Manages concurrency, caching, and coordination between detection algorithms.

🔍 Detection Layer

Runs multiple detection algorithms in parallel. Each algorithm produces independent threat scores that are aggregated.

🤖 AI Layer

Optional component that generates human-readable explanations using locally-running LLMs via Ollama.

Scan Pipeline Flow

When a scan is initiated, packages flow through a multi-stage pipeline:

Scan Pipeline Sequence

Figure 2: Sequence diagram showing the scan pipeline from user request to output

Detection Algorithm Architecture

RUNT (Registry Uncover Naming Threats)

RUNT specializes in detecting typosquatting attacks by comparing package names against known legitimate packages using multiple string similarity algorithms.

RUNT Detection Flow

Figure 3: RUNT uses multiple string analyzers to detect typosquatting

Attack Types Detected

Attack Type	Example	Target
CHARACTER_OMISSION	cros-env	cross-env
CHARACTER_SWAP	axois	axios
CHARACTER_INSERTION	expresss	express
HOMOGLYPH	cross-еnv (Cyrillic е)	cross-env
KEYBOARD_TYPO	lodasj	lodash

DIRT (Dependency Intelligence Risk Tracker)

DIRT assesses business and security risk based on package metadata, maintainer activity, and historical patterns.

📊 Risk Signals

• Package age & download trends
• Maintainer activity
• Dependency count
• Known CVEs
• License type

⚖️ Risk Levels

• LOW – Minimal concern
• MEDIUM – Review recommended
• HIGH – Significant risk
• CRITICAL – Immediate action

GTR (Graph Threat Recognition)

GTR analyzes the dependency graph to identify suspicious patterns:

• Circular Dependencies – Packages that depend on each other
• Excessive Depth – Unusually deep dependency chains
• Shadow Dependencies – Hidden transitive dependencies
• Namespace Confusion – Internal vs external package conflicts

AI Integration Architecture

Falcn’s AI layer provides human-readable explanations for detected threats without sending code to external services.

🔒 Privacy Guarantee

Only package metadata (name, version, similarity scores) is sent to the local LLM. Your source code, environment variables, and file contents never leave your machine.

Local AI Flow

1. Threat detected by detection algorithms
2. Falcn builds a prompt with package metadata only
3. Prompt sent to local Ollama server (localhost:11434)
4. LLM (Llama 3, Mistral, etc.) generates explanation
5. Explanation parsed and included in results

Deployment Architectures

Developer Workstation

Simplest setup – CLI and optional Ollama running locally:

# Install and run
curl -sSL https://falcn.io/install | sh
falcn scan .

CI/CD Pipeline

Integrate with GitHub Actions, GitLab CI, or Jenkins:

- name: Security Scan
  uses: falcn-io/falcn-action@v2
  with:
    mode: fast
    fail-on-violation: true

Enterprise Deployment

For large organizations, deploy Falcn as a service:

• Load Balancer – Distribute scan requests
• API Cluster – Multiple Falcn API servers
• Redis Cache – Shared result caching
• AI Cluster – Dedicated Ollama nodes
• Observability – Splunk, Prometheus, Slack integration

Component Reference

Component	Technology	Purpose
Scanner Engine	Go	Core orchestration and parallel processing
Package Parser	Go	Multi-format manifest parsing
Registry Client	Go + HTTP/2	Efficient registry communication
RUNT Algorithm	Go	String similarity analysis
DIRT Algorithm	Go	Risk scoring engine
GTR Algorithm	Go	Graph analysis
Sandbox	Docker + seccomp	Behavioral analysis
LLM Connector	Go + gRPC	Ollama integration
REST API	Go + Chi router	HTTP interface
Cache Layer	Redis / In-memory	Result caching

📚 Want to Contribute?

Falcn is open source! Check out our Contributing Guide to learn about the codebase structure and how to add new detection algorithms.