Skip to content

Commit fa422f8

Browse files
programmersd21programmersd21
committed
format repo and add screenshots
1 parent bc078ae commit fa422f8

3 files changed

Lines changed: 152 additions & 66 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
lint-and-test:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
python-version: ["3.10", "3.11", "3.12", "3.13"]
15+
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Set up Python ${{ matrix.python-version }}
20+
uses: actions/setup-python@v5
21+
with:
22+
python-version: ${{ matrix.python-version }}
23+
24+
- name: Install dependencies
25+
run: |
26+
pip install -e .
27+
pip install ruff mypy pytest
28+
29+
- name: Lint
30+
run: ruff check .
31+
32+
- name: Type check
33+
run: mypy .
34+
35+
- name: Test
36+
run: pytest .
37+
38+
- name: Format check
39+
run: ruff format --check .

‎README.md‎

Lines changed: 113 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,22 @@
1-
<div align="center">
2-
31
# aur_checker
42

5-
A CLI tool to inspect Arch Linux AUR PKGBUILD files for security risks using static analysis and AI.
3+
![demo](screenshots/image.png)
64

7-
<p align="center">
8-
<img src="https://img.shields.io/github/actions/workflow/status/programmersd21/aur_checker/ci.yml?style=for-the-badge" alt="Build Status">
9-
<img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge" alt="License Badge">
10-
<img src="https://img.shields.io/badge/Python-3.10+-blue?style=for-the-badge&logo=python" alt="Python Version">
11-
</p>
5+
A command-line tool for analyzing Arch Linux AUR PKGBUILD files to identify security risks. Uses static analysis combined with AI-powered inspection.
126

13-
> **Support this project** - [Sponsor](https://github.com/sponsors/programmersd21) or star the repo.
7+
[![Build Status](https://img.shields.io/github/actions/workflow/status/programmersd21/aur_checker/ci.yml?style=flat-square)](https://github.com/programmersd21/aur_checker/actions)
8+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE.md)
9+
[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-blue.svg?style=flat-square)](https://www.python.org/)
1410

15-
---
11+
## Overview
1612

17-
## Pipeline
13+
aur_checker inspects PKGBUILD files for security vulnerabilities and suspicious patterns. It combines static regex-based analysis with AI review to produce a risk assessment score.
1814

15+
**Analysis pipeline:**
1916
```
20-
PKGBUILD → FETCH → STATIC_ANALYSIS → METADATA → SCORING → AI (70% weight) → VERDICT
17+
PKGBUILD → Fetch → Static Analysis → Metadata → Scoring → AI Review → Risk Verdict
2118
```
2219

23-
1. **Fetch** - Downloads PKGBUILD from AUR CGit.
24-
2. **Static analysis** - Regex scan for remote execution, obfuscation, system modification, package manager calls.
25-
3. **Metadata** - AUR RPC v5 info (maintainer, orphan status, age).
26-
4. **Scoring** - Aggregates signals into a 0-100 risk score.
27-
5. **AI** - `gemini-3.1-flash-lite` via `google-genai`. Blended 30/70 (static/AI) for the final verdict.
28-
6. **Output** - Rich terminal output or JSON.
29-
30-
---
31-
3220
## Installation
3321

3422
```bash
@@ -37,84 +25,143 @@ cd aur_checker
3725
pip install -e .
3826
```
3927

40-
---
28+
Requires Python 3.10 or later.
4129

42-
## AI Configuration
43-
44-
AI runs automatically. Set your API key:
45-
46-
| Platform | Command |
47-
|----------|---------|
48-
| Linux/macOS | `export AURCHECKER_AI_API_KEY="your-key"` |
49-
| Windows PowerShell | `$env:AURCHECKER_AI_API_KEY="your-key"` |
50-
51-
Optional overrides:
52-
- `AURCHECKER_AI_MODEL` - model name (default: `gemini-3.1-flash-lite`)
53-
- `AURCHECKER_AI_TIMEOUT` - timeout in ms (default: `120000`)
54-
55-
---
56-
57-
## Usage
30+
## Quick Start
5831

5932
```bash
6033
# Check a single package
6134
aur_checker check keepassx2
6235

63-
# JSON output
64-
aur_checker --json check keepassx2
36+
# Output as JSON
37+
aur_checker check --json keepassx2
6538

6639
# Check multiple packages
6740
aur_checker batch keepassx2 visual-studio-code-bin
41+
42+
# Check from a file
6843
aur_checker batch --file packages.txt
6944

70-
# AI analysis from saved JSON
45+
# AI analysis from previous results
7146
aur_checker explain --input analysis.json
7247

73-
# Check + install (makepkg required)
48+
# Build with makepkg
7449
aur_checker install keepassx2
7550

76-
# Clear cached results
51+
# Clear cached analysis
7752
aur_checker clear-cache
7853
```
7954

80-
---
55+
## Configuration
56+
57+
### API Key
58+
59+
Set your Google Generative AI API key as an environment variable:
8160

82-
## Scoring
61+
```bash
62+
# Linux/macOS
63+
export AURCHECKER_AI_API_KEY="your-api-key"
8364

84-
| Score | Level | Verdict |
85-
|-------|-------|---------|
86-
| 0-20 | LOW | ALLOW |
87-
| 21-50 | MEDIUM | REVIEW |
88-
| 51-100 | HIGH | DENY |
65+
# Windows PowerShell
66+
$env:AURCHECKER_AI_API_KEY="your-api-key"
67+
```
8968

90-
Signals detected by static analysis:
69+
### Optional Settings
9170

92-
| Signal | Trigger | Max weight |
93-
|--------|---------|-----------|
94-
| remote_exec | curl/wget piped to shell | 50 |
95-
| external_calls | Non-source HTTPS URLs | 15 |
96-
| pkg_manager | npm/pip/cargo/go/gem/pacman/yay | 10 |
97-
| orphan_adopted | Package without maintainer | 10 |
98-
| obfuscation | base64, hex, printf+xxd, openssl, eval | 30 |
99-
| system_mod | Writing to /etc, /usr/lib, /opt, /boot | 30 |
100-
| maintainer_changed | Maintainer turnover (always UNKNOWN) | 0 |
71+
| Variable | Purpose | Default |
72+
|----------|---------|---------|
73+
| `AURCHECKER_AI_MODEL` | AI model to use | `gemini-3.1-flash-lite` |
74+
| `AURCHECKER_AI_TIMEOUT` | Request timeout (milliseconds) | `120000` |
10175

102-
---
76+
## How It Works
77+
78+
### Analysis Process
79+
80+
1. **Fetch** - Downloads PKGBUILD from AUR CGit
81+
2. **Static Analysis** - Scans for dangerous patterns via regex
82+
3. **Metadata** - Retrieves AUR RPC v5 package information
83+
4. **Scoring** - Computes 0-100 risk score from signals
84+
5. **AI Review** - Analyzes code structure and context (gemini-3.1-flash-lite)
85+
6. **Verdict** - Blends static (30%) and AI (70%) scores
10386

104-
## Quality Assurance
87+
### Risk Assessment
88+
89+
| Score | Risk Level | Recommendation |
90+
|-------|-----------|-----------------|
91+
| 0-20 | Low | Safe to use |
92+
| 21-50 | Medium | Manual review recommended |
93+
| 51-100 | High | Do not use |
94+
95+
### Security Signals
96+
97+
The static analyzer detects:
98+
99+
| Signal | Pattern | Risk Weight |
100+
|--------|---------|-------------|
101+
| `remote_exec` | Downloads piped to shell (curl/wget pipes) | 50 |
102+
| `external_calls` | Non-source HTTP/HTTPS URLs | 15 |
103+
| `pkg_manager` | Calls to npm, pip, cargo, go, gem, pacman, yay | 10 |
104+
| `orphan_adopted` | Package without active maintainer | 10 |
105+
| `obfuscation` | Base64, hex, eval, openssl, printf+xxd | 30 |
106+
| `system_mod` | Writes to /etc, /usr/lib, /opt, /boot | 30 |
107+
| `maintainer_changed` | Maintainer change detected | 0 |
108+
109+
## Development
110+
111+
### Running Tests
105112

106113
```bash
114+
# Unit tests
107115
pytest
116+
117+
# Type checking
108118
mypy .
119+
120+
# Code style
109121
ruff check .
110122
```
111123

112-
---
124+
### Project Structure
125+
126+
```
127+
aur_checker/
128+
__init__.py
129+
cli.py # Command-line interface
130+
analyzer.py # Static analysis engine
131+
scorer.py # Risk scoring logic
132+
ai.py # AI integration
133+
aur_api.py # AUR RPC client
134+
cache.py # Result caching
135+
```
136+
137+
## Architecture
138+
139+
**Core components:**
140+
141+
- **CLI** - Command-line interface with multiple analysis modes
142+
- **Static Analyzer** - Regex-based pattern detection
143+
- **Risk Scorer** - Aggregates signals into single score
144+
- **AI Engine** - Integrates Google Generative AI for context analysis
145+
- **Cache** - Local storage for previous analyses
146+
- **AUR API Client** - Fetches package metadata and PKGBUILD files
147+
148+
## Limitations
149+
150+
- AI analysis requires valid API key and internet connection
151+
- Static analysis uses pattern matching and may miss sophisticated obfuscation
152+
- Risk scores are heuristic-based and should inform, not replace, manual review
153+
- AI responses depend on model quality and may vary between calls
154+
155+
## Contributing
156+
157+
Contributions welcome. Please open an issue or pull request on GitHub.
113158

114159
## License
115160

116-
MIT. See [LICENSE.md](LICENSE.md).
161+
MIT License. See [LICENSE.md](LICENSE.md) for details.
162+
163+
---
117164

118-
Contact: [geniussantu1983@gmail.com](mailto:geniussantu1983@gmail.com)
165+
**Maintainer:** [geniussantu1983@gmail.com](mailto:geniussantu1983@gmail.com)
119166

120-
</div>
167+
**Repository:** [github.com/programmersd21/aur_checker](https://github.com/programmersd21/aur_checker)

‎screenshots/image.png‎

82.9 KB
Loading

0 commit comments

Comments
 (0)