check-filter 2.5.0

Check URLs that filtered (or not) in Iran.

Check Filtering

A command-line tool to check if domains are filtered (blocked) in Iran by analyzing DNS responses.

🔍 How It Works

This tool checks if a domain is blocked by Iranian ISPs by:

1. Resolving the domain's A record using DNS
2. Comparing the resolved IP addresses against known blocking IPs used by Iranian ISPs
3. Reporting whether the domain is blocked or accessible

Note: This tool can only detect DNS-based blocking and does not have the power to detect other types of filtering or network disorders.

✨ Features

• 🚀 Fast async DNS resolution - Check multiple domains concurrently
• 📋 Multiple input methods - Single domain, comma-separated list, or file
• 🎨 Beautiful CLI output - Rich formatted tables with live updates
• 🔧 Configurable - Custom DNS servers and timeout settings

📋 Requirements

• Python 3.10+

📦 Installation

From PyPI

pip install check-filter

From Source

git clone https://github.com/hatamiarash7/CheckFiltering.git
cd CheckFiltering
poetry install

You can also download the wheel package from the release page.

🚀 Usage

Command Line Interface

Check a Single Domain

check-filter domain github.com

Check Multiple Domains

check-filter domains github.com,google.com,twitter.com

Check Domains from File

Create a file with domain names (one per line). Lines starting with # are treated as comments:

# Social media
github.com
twitter.com
facebook.com

# Development
gitlab.com
stackoverflow.com

Then run:

check-filter file domains.txt

Show Version

check-filter --version
# or
check-filter -v

Show Help

check-filter --help
check-filter domain --help
check-filter domains --help
check-filter file --help

As a Python Library

import asyncio
from check_filter import DomainChecker, FilterStatus

async def main():
    checker = DomainChecker()
    
    # Check a single domain
    result = await checker.acheck("google.com")
    print(f"{result.domain}: {result.status.value}")
    print(f"Blocked: {result.is_blocked}")
    print(f"IPs: {result.ips}")
    
    # Check multiple domains concurrently
    results = await checker.acheck_many([
        "google.com",
        "twitter.com",
        "github.com",
    ])
    
    for result in results:
        status = "🚫 Blocked" if result.is_blocked else "✅ Free"
        print(f"{result.domain}: {status}")

asyncio.run(main())

Custom Configuration

from check_filter import DomainChecker

# Use custom blocked IPs and DNS servers
checker = DomainChecker(
    blocked_ips={"10.10.34.34", "10.10.34.35"},
    nameservers=["8.8.8.8", "8.8.4.4"],
    timeout=10.0,
)

Using CheckResult

from check_filter import CheckResult, FilterStatus

# CheckResult is a dataclass with useful properties
result = await checker.acheck("example.com")

# Access properties
print(result.domain)      # "example.com"
print(result.status)      # FilterStatus.FREE
print(result.is_free)     # True
print(result.is_blocked)  # False
print(result.ips)         # frozenset({'93.184.216.34'})
print(result.error)       # None (or error message if failed)

# Backward compatible tuple unpacking
domain, is_free = result

🛠️ Development

Setup Development Environment

# Clone the repository
git clone https://github.com/hatamiarash7/CheckFiltering.git
cd CheckFiltering

# Install dependencies with dev tools
make install-dev

Available Commands

make help           # Show all available commands
make test           # Run tests
make test-cov       # Run tests with coverage report
make lint           # Run all linters
make lint-fix       # Run linters with auto-fix
make format         # Format code with black and isort
make type-check     # Run type checking with mypy
make check          # Run all checks (format, lint, type-check, test)
make build          # Build package
make clean          # Clean build artifacts

Running Tests

# Run all tests
make test

# Run tests with coverage
make test-cov

# Run fast tests (exclude slow/integration tests)
make test-fast

📄 API Reference

DomainChecker

Main class for checking domain filtering status.

DomainChecker(
    blocked_ips: Set[str] | None = None,  # Custom blocked IPs
    nameservers: list[str] | None = None,  # DNS servers to use
    timeout: float = 5.0,                  # DNS query timeout
)

Methods:

• acheck(domain: str) -> CheckResult - Check a single domain
• acheck_many(domains: list[str]) -> list[CheckResult] - Check multiple domains

CheckResult

Dataclass containing the result of a domain check.

Attributes:

• domain: str - The checked domain
• status: FilterStatus - The filtering status
• ips: frozenset[str] - Resolved IP addresses
• error: str | None - Error message if check failed

Properties:

• is_blocked: bool - True if domain is blocked
• is_free: bool - True if domain is not blocked

FilterStatus

Enum with possible filtering statuses:

• FREE - Domain is accessible
• BLOCKED - Domain is blocked
• ERROR - Check failed (timeout, etc.)
• UNKNOWN - Domain doesn't exist (NXDOMAIN)

---

💛 Support

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch: git checkout -b feature/my-new-feature
3. Install development dependencies: make install-dev
4. Make your changes and add tests
5. Run checks: make check
6. Commit your changes: git commit -am 'Add some feature'
7. Push to the branch: git push origin feature/my-new-feature
8. Submit a pull request

🐛 Issues

Found a bug or have a suggestion? Please open an issue.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.