Metadata-Version: 2.4
Name: perimeter-scan
Version: 0.1.0
Summary: Passive external attack-surface scanner — find your exposed subdomains, expiring certs, missing security headers, and dangling DNS before attackers do.
Author: Captain
License: MIT
Project-URL: Homepage, https://perimeter-hq.com
Project-URL: Source, https://github.com/MrAbubaker1/perimeter-scan
Keywords: security,attack-surface,subdomain,recon,dns,tls,osint,appsec
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: dnspython>=2.6
Requires-Dist: cryptography>=42.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# perimeter-scan

**Passive external attack-surface scanner.** Find your exposed subdomains, expiring
certs, missing security headers, and dangling DNS that could be hijacked — before an
attacker (or a prospect's security team) does.

One command, no agent, no signup:

```console
$ perimeter-scan example.com
```

It's **passive**: it reads public Certificate Transparency logs and DNS, and makes
standard web requests to the hosts it finds. No exploitation, no port scanning, no
authenticated probing. **Only scan domains you own or are authorized to assess.**

## What it checks

| Check | How |
|-------|-----|
| **Subdomains** | enumerated from public Certificate Transparency logs (crt.sh) |
| **TLS hygiene** | expired, expiring-soon, and self-signed certificates |
| **Security headers** | missing HSTS / CSP / anti-clickjacking / MIME-sniffing headers |
| **Subdomain takeover** | dangling CNAMEs pointing at unclaimed third-party services |

## Install

```console
$ pipx install perimeter-scan      # recommended (isolated)
# or
$ pip install perimeter-scan
```

Requires Python 3.11+.

## Usage

```console
$ perimeter-scan example.com                  # human-readable report
$ perimeter-scan example.com --json           # machine-readable JSON
$ perimeter-scan example.com --min-severity high   # only high+ findings
$ perimeter-scan example.com --max-subdomains 100  # scan more hosts
$ perimeter-scan example.com --fail-on high   # exit 1 if any high+ finding (for CI)
```

### In CI — fail the build on a new exposure

```yaml
# .github/workflows/attack-surface.yml
- run: pipx install perimeter-scan
- run: perimeter-scan yourcompany.com --fail-on high --json
```

### As a library

```python
import asyncio
from perimeter_scan import passive_scan, ScanConfig

result = asyncio.run(passive_scan("example.com", config=ScanConfig(max_subdomains=50)))
print(result.risk_score, result.counts_by_severity())
for f in result.findings:
    print(f.severity.value, f.asset, f.title)
```

## A one-time scan is a snapshot. Your attack surface changes every deploy.

`perimeter-scan` is the open-source scanner behind **[Perimeter](https://perimeter-hq.com)**.
The CLI tells you what's exposed *right now*. Perimeter runs it continuously, remembers
what it saw last time, and **alerts you the moment something new appears** — a fresh
subdomain, a cert about to lapse, a dangling record someone could hijack — so you find
it before anyone else does.

→ **[Monitor your domain continuously](https://perimeter-hq.com)**

## License

MIT. Contributions welcome.
