Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
116 lines (81 loc) · 2.75 KB

CONTRIBUTING.md

File metadata and controls

116 lines (81 loc) · 2.75 KB
Raw

Contributing

Nebraska is an open-source OSINT tool and contributions are welcome. Whether you want to add a new platform, fix a bug, or improve detection accuracy — here's how.

The easiest way: add a new site

This requires no programming knowledge. You just create a text file.

1. Investigate the site

Open two URLs in your browser:

  • A real profile: e.g. https://example.com/user/realuser
  • A fake profile: e.g. https://example.com/user/xxxxxxxxxzzzzz999

Note:

  • What HTTP status does each return? (Open DevTools → Network tab)
  • Does the "not found" page contain specific text?
  • Does the real profile page contain specific text like "followers" or "avatar"?

2. Create the YAML

Create a file nebraska/config/sites/example.yaml:

site_name: Example
category: social
enabled: true
url_home: https://example.com
profile_url_template: "https://example.com/user/{username}"
method: GET
expected_status_on_found: [200]
expected_status_on_not_found: [404]

positive_indicators:
  - "text-only-on-real-profiles"

negative_indicators:
  - "text-only-on-not-found-pages"

error_indicators:
  - "rate limit"

timeout: 10.0
rate_limit_hint: 1.0
reliability_score: 0.80

3. Test

python -m nebraska validate-sites
python -m nebraska site Example realuser
python -m nebraska site Example xxxxxxxxxzzzzz999

First should be FOUND, second should be NOT_FOUND. If both work, open a PR.

Reliability score guide

Score Use when
0.90+ Clean 404 on missing users, never blocks, very reliable
0.75-0.89 Usually reliable, occasional quirks
0.60-0.74 Sometimes blocks, needs JS, or returns 200 for everything
0.40-0.59 Frequently blocks or gives unreliable responses

Code contributions

Setup

git clone https://github.com/YOUR_USERNAME/nebraska.git
cd nebraska
pip install requests click pyyaml

Before submitting

python -m nebraska validate-sites          # All sites valid
python -m unittest discover -s tests -v    # All tests pass

Guidelines

  • Run the tests before every PR
  • If you add functionality, add tests for it
  • Keep functions small and focused
  • Use type hints
  • Follow the patterns already in the codebase

Bug reports

Open an issue with:

  • The exact command you ran
  • What you expected vs what happened
  • Your OS and Python version (python --version)
  • The full error output

Responsible use

Nebraska is built for legitimate OSINT research. When contributing:

  • Do not add sites that require authentication to check usernames
  • Do not add methods that bypass CAPTCHAs or rate limits
  • Do not add functionality that scrapes private data
  • Respect the rate_limit_hint field — don't set it to 0 for sites that need throttling