aljaz/Auditor
1
0
Fork 0
mirror of https://github.com/aljazceru/Auditor.git synced 2025-12-17 11:24:19 +01:00
Code Issues Packages Projects Releases Wiki Activity

Updated readme.md

Browse Source 
Restructured the placements and made it more to the point.
This commit is contained in:
TheAuditorTool
2025-09-08 01:40:49 +07:00
parent ca866e188a
commit 32e9aad1db
1 changed files with 152 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files

308
README.md
View File

@@ -1,153 +1,3 @@
### The Search for Ground Truth in an Age of AI
My background is in systems architecture/infrastructure, not professional software development. I have only been "coding/developing" for little over 3 months. This gives me a unique perspective: I can see the forest, but I'm blind to the individual trees of the code. After immersing myself for 500+ hours in AI-assisted development, I concluded that the entire ecosystem is built on a fundamentally flawed premise: it lacks a source of **ground truth**.
From start to launch on GitHub took me about a month across 250 active hours in front of the computer, for anyone that wonders or cares :P
---
### The Problem: A Cascade of Corrupted Context
Most AI development tools try to solve the wrong problem. They focus on perfecting the *input*—better prompts, more context—but they ignore the critical issue of **compounding deviation**.
An LLM is a powerful statistical engine, but it doesn't *understand*. The modern AI workflow forces this engine to play a high-stakes game of "telephone," where the original intent is corrupted at every step:
1. A human has an idea.
2. An AI refines it into a prompt.
3. Other tools add their own interpretive layers.
4. The primary AI assistant (e.g., Claude Opus) interprets the final, distorted prompt to generate code.
As a rookie "developer," the only thing I could trust was the raw output: the code and its errors. In a vacuum of deep programming knowledge, these facts were my only anchors.
This architectural flaw is amplified by two dangerous behaviours inherent to AI assistants:
* **Security Theater**: AI assistants are optimized to "make it work," which often means introducing rampant security anti-patterns like hardcoded credentials, disabled authentication, and the pervasive use of `as any` in TypeScript. This creates a dangerous illusion of progress.
* **Context Blindness**: With aggressive context compaction, an AI never sees the full picture. It works with fleeting snapshots of code, forcing it to make assumptions instead of decisions based on facts.
---
### The Solution: `TheAuditor`
`TheAuditor` is the antidote. It was built to stop "vibe coding" your way into security and quality assurance nightmares. Its mission is to provide an incorruptible source of **ground truth** for both the developer and their AI assistant.
Its philosophy is a direct rejection of the current trend:
* **It Orchestrates Verifiable Data.** The tool runs a suite of industry-standard linters and security scanners, preserving the raw, unfiltered output from each. It does not summarize or interpret this core data.
* **It's Built for AI Consumption.** The tool's primary engineering challenge is to adapt this raw truth into structured, AI-digestible chunks. It ensures the AI works with facts, not faulty summaries.
* **It's Focused and Extensible.** The initial focus is on Python and the Node.js ecosystem, but the modular, pattern-based architecture is designed to invite contributions for other languages and frameworks.
`TheAuditor` is not a replacement for a formal third-party audit. It is an engineering tool designed to catch the vast majority of glaring issues—from the OWASP Top 10 to common framework anti-patterns. **Its core commitment is to never cross the line from verifiable truth into semantic interpretation.**
Every AI assistant - Claude Code, Cursor, Windsurf, Copilot - they're all blind. They can write code but can't
verify it's secure, correct, or complete. TheAuditor gives them eyes.
Why This Matters
1. Tool Agnostic - Works with ANY AI assistant or IDE
- aud full from any terminal
- Results in .pf/readthis/ ready for any LLM
2. AI Becomes Self-Correcting
- AI writes code
- AI runs aud full
- AI reads the ground truth
- AI fixes its own mistakes
- Recursive loop until actually correct
3. No Human Intervention Required
- You never touch the terminal
- The AI runs everything
- You just review and approve
The Genius Architecture
Human: "Add authentication to my app"
↓
AI: *writes auth code*
↓
AI: `aud full`
↓
AI: *reads .pf/readthis/*
↓
AI: "Found 3 security issues, fixing..."
↓
AI: *fixes issues*
↓
AI: `aud full`
↓
AI: "Clean. Authentication complete."
Market Reality Check
Every developer using AI assistants has this problem:
- AI writes insecure code
- AI introduces bugs
- AI doesn't see the full picture
- AI can't verify its work
TheAuditor solves ALL of this. It's not a "nice to have" - it's the missing piece that makes AI development
actually trustworthy.
I've built the tool that makes AI assistants production-ready.
This isn't competing with SonarQube/SemGrep. This is creating an entirely new category: AI Development Verification
Tools.
---
### Important: Antivirus Software Interaction
#### Why TheAuditor Triggers Antivirus Software
TheAuditor is a security scanner that identifies vulnerabilities in your code. By its very nature, it must:
1. **Read and analyze security vulnerabilities** - SQL injection, XSS attacks, hardcoded passwords
2. **Write these findings to disk** - Creating reports with exact code snippets as evidence
3. **Process files rapidly** - Scanning entire codebases in parallel for efficiency
This creates an inherent conflict with antivirus software, which sees these exact same behaviours as potentially malicious. When TheAuditor finds and documents a SQL injection vulnerability in your code, your antivirus sees us writing "malicious SQL injection patterns" to disk - because that's literally what we're doing, just for legitimate security analysis purposes.
#### Performance Impact You May Experience
When running TheAuditor, you may notice:
- **Increased antivirus CPU usage** - Your AV will scan every file we read AND every finding we write
- **Approximately 10-50% performance reduction, depending on software.** - Both TheAuditor and your AV are reading the same files simultaneously
- **Occasional delays or pauses** - Your AV may temporarily quarantine our output files for deeper inspection
This is not a bug or inefficiency in TheAuditor - it's the unavoidable consequence of two security tools doing their jobs simultaneously.
#### Our Stance on Antivirus
**We do NOT recommend:**
- ❌ Disabling your antivirus software
- ❌ Adding TheAuditor to your exclusion/whitelist
- ❌ Reducing your system's security in any way
Your antivirus is correctly identifying that we're writing security vulnerability patterns to disk. That's exactly what we do - we find vulnerabilities and document them. The fact that your AV is suspicious of this behavior means it's working properly.
#### What We've Done to Minimize Impact
1. **Intelligent resource management** - We automatically reduce parallel workers when system resources are constrained
2. **Pattern defanging** - We insert invisible characters into dangerous patterns to reduce false positives
3. **Adaptive performance** - We monitor CPU and RAM usage to avoid overwhelming your system
#### The Industry Reality
This is not a problem unique to TheAuditor. Every legitimate security scanner faces this same issue:
- **GitHub Advanced Security** runs in isolated cloud containers to avoid this
- **Commercial SAST tools** require enterprise AV exceptions
- **Popular scanners** explicitly document AV conflicts in their installation guides
The fundamental paradox: A tool that finds security vulnerabilities must write those vulnerabilities to disk, which makes it indistinguishable from malware to an antivirus. There is no technical solution to this - it's the inherent nature of security analysis tools.
#### What This Means for You
- Run TheAuditor when system load is low for best performance
- Expect the analysis to take longer than the raw processing time due to AV overhead
- If your AV quarantines output files in `.pf/`, you may need to restore them manually
- Consider running TheAuditor in a controlled environment if performance is critical
We believe in complete transparency about these limitations. This interaction with antivirus software is not a flaw in TheAuditor - it's proof that both your AV and our scanner are doing exactly what they're designed to do: identify and handle potentially dangerous code patterns.
---
# TheAuditor
Offline-First, AI-Centric SAST & Code Intelligence Platform
@@ -172,7 +22,7 @@ Unlike traditional SAST tools, TheAuditor is designed specifically for AI-assist
pip install -e .
# MANDATORY: Setup TheAuditor environment (required for all functionality)
This installs .auditor_venv to what project you want to analyse.
# This installs .auditor_venv to the project you want to analyze
aud setup-claude --target .
# Initialize your project
@@ -187,13 +37,93 @@ ls .pf/readthis/
That's it! TheAuditor will analyze your codebase and generate AI-ready reports in `.pf/readthis/`.
## The Solution: TheAuditor
## Documentation
TheAuditor is the antidote. It was built to stop "vibe coding" your way into security and quality assurance nightmares. Its mission is to provide an incorruptible source of **ground truth** for both the developer and their AI assistant.
- **[How to Use](HOWTOUSE.md)** - Complete installation and usage guide
- **[Architecture](ARCHITECTURE.md)** - Technical architecture and design patterns
- **[Contributing](CONTRIBUTING.md)** - How to contribute to TheAuditor
- **[Roadmap](ROADMAP.md)** - Future development plans
Its philosophy is a direct rejection of the current trend:
- **It Orchestrates Verifiable Data.** The tool runs a suite of industry-standard linters and security scanners, preserving the raw, unfiltered output from each. It does not summarize or interpret this core data.
- **It's Built for AI Consumption.** The tool's primary engineering challenge is to adapt this raw truth into structured, AI-digestible chunks. It ensures the AI works with facts, not faulty summaries.
- **It's Focused and Extensible.** The initial focus is on Python and the Node.js ecosystem, but the modular, pattern-based architecture is designed to invite contributions for other languages and frameworks.
TheAuditor is not a replacement for a formal third-party audit. It is an engineering tool designed to catch the vast majority of glaring issues—from the OWASP Top 10 to common framework anti-patterns. **Its core commitment is to never cross the line from verifiable truth into semantic interpretation.**
Every AI assistant - Claude Code, Cursor, Windsurf, Copilot - they're all blind. They can write code but can't verify it's secure, correct, or complete. TheAuditor gives them eyes.
### Why This Matters
1. **Tool Agnostic** - Works with ANY AI assistant or IDE
- `aud full` from any terminal
- Results in `.pf/readthis/` ready for any LLM
2. **AI Becomes Self-Correcting**
- AI writes code
- AI runs `aud full`
- AI reads the ground truth
- AI fixes its own mistakes
- Recursive loop until actually correct
3. **No Human Intervention Required**
- You never touch the terminal
- The AI runs everything
- You just review and approve
### The Genius Architecture
```
Human: "Add authentication to my app"
↓
AI: *writes auth code*
↓
AI: `aud full`
↓
AI: *reads .pf/readthis/*
↓
AI: "Found 3 security issues, fixing..."
↓
AI: *fixes issues*
↓
AI: `aud full`
↓
AI: "Clean. Authentication complete."
```
### Market Reality Check
Every developer using AI assistants has this problem:
- AI writes insecure code
- AI introduces bugs
- AI doesn't see the full picture
- AI can't verify its work
TheAuditor solves ALL of this. It's not a "nice to have" - it's the missing piece that makes AI development actually trustworthy.
I've built the tool that makes AI assistants production-ready. This isn't competing with SonarQube/SemGrep. This is creating an entirely new category: **AI Development Verification Tools**.
## The Search for Ground Truth in an Age of AI
My background is in systems architecture/infrastructure, not professional software development. I have only been "coding/developing" for little over 3 months. This gives me a unique perspective: I can see the forest, but I'm blind to the individual trees of the code. After immersing myself for 500+ hours in AI-assisted development, I concluded that the entire ecosystem is built on a fundamentally flawed premise: it lacks a source of **ground truth**.
From start to launch on GitHub took me about a month across 250 active hours in front of the computer, for anyone that wonders or cares :P
### The Problem: A Cascade of Corrupted Context
Most AI development tools try to solve the wrong problem. They focus on perfecting the *input*—better prompts, more context—but they ignore the critical issue of **compounding deviation**.
An LLM is a powerful statistical engine, but it doesn't *understand*. The modern AI workflow forces this engine to play a high-stakes game of "telephone," where the original intent is corrupted at every step:
1. A human has an idea.
2. An AI refines it into a prompt.
3. Other tools add their own interpretive layers.
4. The primary AI assistant (e.g., Claude Opus) interprets the final, distorted prompt to generate code.
As a rookie "developer," the only thing I could trust was the raw output: the code and its errors. In a vacuum of deep programming knowledge, these facts were my only anchors.
This architectural flaw is amplified by two dangerous behaviours inherent to AI assistants:
- **Security Theater**: AI assistants are optimized to "make it work," which often means introducing rampant security anti-patterns like hardcoded credentials, disabled authentication, and the pervasive use of `as any` in TypeScript. This creates a dangerous illusion of progress.
- **Context Blindness**: With aggressive context compaction, an AI never sees the full picture. It works with fleeting snapshots of code, forcing it to make assumptions instead of decisions based on facts.
## Key Features
@@ -274,6 +204,70 @@ Insights modules add interpretive scoring on top of factual data:
- **Recommendations**: Actionable improvement suggestions
- **ML Predictions**: Pattern-based issue prediction
## Important: Antivirus Software Interaction
#### Why TheAuditor Triggers Antivirus Software
TheAuditor is a security scanner that identifies vulnerabilities in your code. By its very nature, it must:
1. **Read and analyze security vulnerabilities** - SQL injection, XSS attacks, hardcoded passwords
2. **Write these findings to disk** - Creating reports with exact code snippets as evidence
3. **Process files rapidly** - Scanning entire codebases in parallel for efficiency
This creates an inherent conflict with antivirus software, which sees these exact same behaviours as potentially malicious. When TheAuditor finds and documents a SQL injection vulnerability in your code, your antivirus sees us writing "malicious SQL injection patterns" to disk - because that's literally what we're doing, just for legitimate security analysis purposes.
#### Performance Impact You May Experience
When running TheAuditor, you may notice:
- **Increased antivirus CPU usage** - Your AV will scan every file we read AND every finding we write
- **Approximately 10-50% performance reduction, depending on software.** - Both TheAuditor and your AV are reading the same files simultaneously
- **Occasional delays or pauses** - Your AV may temporarily quarantine our output files for deeper inspection
This is not a bug or inefficiency in TheAuditor - it's the unavoidable consequence of two security tools doing their jobs simultaneously.
#### Our Stance on Antivirus
**We do NOT recommend:**
- ❌ Disabling your antivirus software
- ❌ Adding TheAuditor to your exclusion/whitelist
- ❌ Reducing your system's security in any way
Your antivirus is correctly identifying that we're writing security vulnerability patterns to disk. That's exactly what we do - we find vulnerabilities and document them. The fact that your AV is suspicious of this behavior means it's working properly.
#### What We've Done to Minimize Impact
1. **Intelligent resource management** - We automatically reduce parallel workers when system resources are constrained
2. **Pattern defanging** - We insert invisible characters into dangerous patterns to reduce false positives
3. **Adaptive performance** - We monitor CPU and RAM usage to avoid overwhelming your system
#### The Industry Reality
This is not a problem unique to TheAuditor. Every legitimate security scanner faces this same issue:
- **GitHub Advanced Security** runs in isolated cloud containers to avoid this
- **Commercial SAST tools** require enterprise AV exceptions
- **Popular scanners** explicitly document AV conflicts in their installation guides
The fundamental paradox: A tool that finds security vulnerabilities must write those vulnerabilities to disk, which makes it indistinguishable from malware to an antivirus. There is no technical solution to this - it's the inherent nature of security analysis tools.
#### What This Means for You
- Run TheAuditor when system load is low for best performance
- Expect the analysis to take longer than the raw processing time due to AV overhead
- If your AV quarantines output files in `.pf/`, you may need to restore them manually
- Consider running TheAuditor in a controlled environment if performance is critical
We believe in complete transparency about these limitations. This interaction with antivirus software is not a flaw in TheAuditor - it's proof that both your AV and our scanner are doing exactly what they're designed to do: identify and handle potentially dangerous code patterns.
---
## Documentation
- **[How to Use](HOWTOUSE.md)** - Complete installation and usage guide
- **[Architecture](ARCHITECTURE.md)** - Technical architecture and design patterns
- **[Contributing](CONTRIBUTING.md)** - How to contribute to TheAuditor
- **[Roadmap](ROADMAP.md)** - Future development plans
## Contributing
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for:
@@ -289,6 +283,8 @@ We especially need help with:
- **Ruby on Rails** detection
- **C#/.NET** analysis
---
## License
AGPL-3.0