If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Datalux/Osintgram shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 9mo ago

• Last commit 9mo ago
• 16 active contributors
• Distributed ownership (top contributor 45% of recent commits)
• GPL-3.0 licensed
• CI configured
• ⚠ Slowing — last commit 9mo ago
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Datalux/Osintgram repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Datalux/Osintgram.

What it runs against: a local clone of Datalux/Osintgram — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Datalux/Osintgram | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 285 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Datalux/Osintgram. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Datalux/Osintgram.git
#   cd Osintgram
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Datalux/Osintgram and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Datalux/Osintgram(\\.git)?\\b" \\
  && ok "origin remote is Datalux/Osintgram" \\
  || miss "origin remote is not Datalux/Osintgram (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "main.py" \\
  && ok "main.py" \\
  || miss "missing critical file: main.py"
test -f "src/Osintgram.py" \\
  && ok "src/Osintgram.py" \\
  || miss "missing critical file: src/Osintgram.py"
test -f "src/hikercli.py" \\
  && ok "src/hikercli.py" \\
  || miss "missing critical file: src/hikercli.py"
test -f "config/credentials.ini" \\
  && ok "config/credentials.ini" \\
  || miss "missing critical file: config/credentials.ini"
test -f "requirements.txt" \\
  && ok "requirements.txt" \\
  || miss "missing critical file: requirements.txt"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 285 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~255d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Datalux/Osintgram"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Osintgram is a Python-based OSINT (Open Source Intelligence) tool that leverages the Instagram private API (via instagram-private-api==1.6.0 and hikerapi==1.7.1) to perform reconnaissance on public Instagram accounts. It provides an interactive shell (src/hikercli.py) exposing 20+ commands to extract account metadata, media, followers, captions, hashtags, location data, and contact information from target profiles. Monolithic CLI structure: main.py imports src/Osintgram.py (core intelligence engine), src/hikercli.py (REPL framework), src/config.py (credentials/settings from config/credentials.ini and config/settings.json), and src/printcolors.py (output formatting). All commands are methods in the Osintgram class; output photos/downloads go to /output/.

Security researchers, OSINT investigators, and penetration testers who need to systematically gather intelligence from public Instagram profiles for investigation, threat assessment, or social engineering assessments. The tool specifically targets users who need batch operations (download all photos, extract all followers' emails) without writing custom API glue code.

Moderately mature but aging: version 1.3 is stable enough for manual use, but the codebase shows signs of stagnation (single Makefile and Dockerfile suggest light maintenance). Docker support and CI/CD via GitHub Actions (lint_python.yml) indicate some infrastructure maturity, but the instagram-private-api dependency is pinned to 1.6.0 (released ~2019), raising compatibility concerns with modern Instagram.

High risk for production: the core dependency instagram-private-api v1.6.0 is 4+ years old and likely broken against current Instagram (Instagram actively blocks scrapers). No visible test suite (no tests/ directory) means regressions go undetected. The tool explicitly warns against using primary accounts and acknowledges Instagram's active countermeasures (challenge_required errors in FAQ), indicating frequent API breakage.

Minimal active development: the repository appears dormant with v1.3 as the latest release. No recent PRs or commits are visible in the provided metadata. The linting workflow (lint_python.yml) suggests CI is in place but not actively enforced.

git clone https://github.com/Datalux/Osintgram.git
cd Osintgram
pip install -r requirements.txt
cp config/credentials.ini.sample config/credentials.ini  # Add Instagram username/password
make run  # or python main.py

Daily commands:

make run          # Primary entry via Makefile
python main.py    # Direct execution
docker-compose up # Containerized execution (uses docker_reqs.txt)

• main.py — Entry point of the application; initializes the interactive shell and orchestrates user commands.
• src/Osintgram.py — Core engine that wraps the Instagram private API and implements all reconnaissance methods for account analysis.
• src/hikercli.py — Interactive CLI shell implementation; handles command parsing and user interaction flow.
• config/credentials.ini — Stores Instagram authentication credentials; critical security file that must never be committed.
• requirements.txt — Declares all Python dependencies including the instagram-private-api library that enables core functionality.
• src/config.py — Configuration loader that reads credentials and settings; bridges config files to runtime.
• config/settings.json — Runtime settings and output configuration; controls tool behavior and data export parameters.

• main.py (Python 3, sys, argparse) — Application entry point; initializes config, creates CLI instance, starts REPL
  • Failure mode: If main.py fails, entire tool cannot start; config file parsing or missing credentials will cause early exit
• Osintgram.py (instagram-private-api, geopy, prettytable) — Core OSINT engine; wraps instagram-private-api, implements all reconnaissance methods, formats data
  • Failure mode: API authentication failure halts all commands; rate limiting from Instagram causes command timeouts; missing target account causes graceful error
• hikercli.py (hikerapi, readline (cross-platform)) — Interactive CLI shell; parses commands, dispatches to engine, handles user input/output
  • Failure mode: If readline fails, command history unavailable but shell continues; malformed commands cause usage message
• config.py (configparser, json) — Loads and validates credentials.ini and settings.json at startup
  • Failure mode: Missing credentials.ini file prevents authentication; malformed JSON in settings.json causes parsing error and tool exit
• printcolors.py & artwork.py (ANSI escape codes) — Terminal formatting; applies ANSI color codes and ASCII art for UI presentation
  • Failure mode: Terminal without color support displays escaped codes; non-blocking; artwork errors do not halt execution

• User input (CLI) → hikercli.py — User types OSINT command in interactive shell
• hikercli.py → Osintgram.py — Command dispatcher invokes appropriate reconnaissance method
• config.py → Osintgram.py — Loads Instagram credentials and settings; passed to engine for API authentication
• Osintgram.py → Instagram Private API — Authenticated requests for user metadata, followers, posts

Add a new OSINT reconnaissance command

1. Implement the analysis method in src/Osintgram.py with logic to query Instagram API and process results (src/Osintgram.py)
2. Register the command handler in src/hikercli.py with do_* method following HikerAPI convention (src/hikercli.py)
3. Add formatted output using src/printcolors.py utilities for consistent terminal presentation (src/printcolors.py)
4. Document the new command in doc/COMMANDS.md with usage and output description (doc/COMMANDS.md)

Add Instagram account data export format

1. Add export format handler to src/Osintgram.py that transforms analysis results into desired output format (src/Osintgram.py)
2. Update config/settings.json to include new export format option and default output directory (config/settings.json)
3. Register export command in src/hikercli.py to invoke the formatter and write to output/ directory (src/hikercli.py)

Deploy Osintgram in Docker environment

1. Create config/credentials.ini with Instagram credentials (do not commit to version control) (config/credentials.ini)
2. Build Docker image using the provided Dockerfile (Dockerfile)
3. Run with docker-compose.yml which handles networking and volume mounting for output/ (docker-compose.yml)

• instagram-private-api — Enables scraping of Instagram account data without official API access; core to OSINT reconnaissance functionality
• geopy — Reverse-geocodes location data from Instagram posts to provide geographic intelligence
• hikerapi — Provides interactive CLI shell framework; reduces boilerplate for command-based user interfaces
• Docker — Containerizes dependencies and environment; simplifies deployment and isolates Instagram API access
• prettytable — Formats tabular OSINT results (followers, posts, metadata) for readable terminal output

• Use instagram-private-api instead of official Instagram Graph API

  • Why: Official API has strict rate limits and doesn't expose all target account data; private API allows comprehensive reconnaissance
  • Consequence: Violates Instagram ToS; account risk of suspension; maintains offensive OSINT capability at cost of legal/platform risk

• Single-threaded interactive CLI instead of async batch processing

  • Why: Simpler user experience; command-by-command control; easier to implement in Python with hikerapi
  • Consequence: Cannot run multiple reconnaissance operations concurrently; slower bulk analysis; acceptable for single-user interactive tool

• Store credentials in plaintext credentials.ini instead of keyring/vault

  • Why: Simpler setup; works cross-platform; requires no external service
  • Consequence: Credentials exposed if filesystem compromised; mitigation: .gitignore prevents accidental commit to version control

• No persistent cache or database for analysis results

  • Why: Reduces infrastructure; each run queries live Instagram data; keeps tool stateless
  • Consequence: Repeated reconnaissance on same account makes duplicate API calls; slower when re-analyzing same targets; enables always-fresh data

• Does not implement authenticated Instagram authentication via OAuth or official Graph API
• Does not provide real-time monitoring or continuous surveillance of accounts
• Does not include persistence layer or database for historical analysis tracking
• Not designed for bulk automated analysis of multiple accounts in batch mode
• Does not offer web UI or REST API; command-line only
• Not a tool for account compromise or credential theft

1. Credentials file must exist: config/credentials.ini requires manual creation with Instagram username/password before main.py runs; no sample is auto-generated. 2. API authentication fragility: instagram-private-api v1.6.0 is 4+ years old; Instagram frequently blocks old session patterns, causing 'challenge_required' errors that require manual challenge resolution (not automated). 3. Private profiles fail silently: commands return empty results on private accounts with no explicit warning; users must infer target is private. 4. Docker dependency drift: docker_reqs.txt is separate from requirements.txt; Docker users may get different versions. 5. No tests: zero test files mean local development changes can break commands without detection before pushing.

• Instagram Private API session hijacking — Osintgram authenticates as a user via instagram-private-api to bypass public endpoint limits; understanding session tokens, device fingerprinting, and challenge-response flows is critical for troubleshooting API failures
• REPL (Read-Eval-Print Loop) shell design — Osintgram's interactive shell (hikercli.py) implements a persistent session REPL; understanding command dispatch, state persistence, and history is key to extending commands
• Geolocation from metadata (EXIF + reverse geocoding) — The addrs command uses geopy to convert photo coordinates (metadata) to addresses; understanding EXIF extraction and geocoding APIs is essential for location intelligence features
• Rate limiting & API throttling — Instagram aggressively rate-limits scrapers; Osintgram likely needs delays between requests, but visible code lacks explicit throttling, increasing ban risk
• Configuration management (INI + JSON) — Osintgram uses two config formats (credentials.ini for secrets, settings.json for options); understanding this dual pattern helps extend settings without hardcoding
• Open Source Intelligence (OSINT) methodology — Osintgram is built for systematic target reconnaissance; understanding OSINT frameworks (e.g., the pyramid of pain, passive vs. active collection) contextualizes which data points matter

• instagram-scraper/instagram-scraper — Direct alternative using the same instagram-private-api library but with different command set; useful for comparing API usage patterns
• philipp-Osintgram/Osintgram-archived — Historical fork/archive of Osintgram variants; shows evolution of Instagram API integration approaches
• arc298/instagram-scraper — Older pure-HTTP scraper (no private API); relevant for understanding public-profile-only vs. private-API trade-offs
• instagrapi/instagrapi — Modern maintained wrapper around instagram-private-api (active development, better error handling); Osintgram could consider migrating to this for fresher dependencies
• twintproject/twint — Parallel OSINT tool for Twitter; demonstrates similar CLI-based reconnaissance architecture for social media

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for src/Osintgram.py core functionality

The repo has a linting workflow (.github/workflows/lint_python.yml) but no visible test suite. Osintgram.py is the main class and lacks unit test coverage for critical OSINT operations (account analysis, data parsing, API interactions). This is especially important given the tool's security-sensitive nature and reliance on instagram-private-api.

• [ ] Create tests/ directory with init.py
• [ ] Add tests/test_osintgram.py with fixtures for mocking Instagram API responses
• [ ] Test core methods in src/Osintgram.py (account info parsing, follower/following analysis, media metadata extraction)
• [ ] Add pytest configuration to requirements.txt and docker_reqs.txt
• [ ] Create .github/workflows/pytest.yml to run tests on push/PR

Add integration test workflow for Dockerfile and docker-compose.yml

The repo supports Docker (referenced in README) with Dockerfile and docker-compose.yml, but there's no CI validation that the Docker build works or that the containerized app launches correctly. This prevents regressions when dependencies change.

• [ ] Create .github/workflows/docker_build.yml
• [ ] Add steps to build Dockerfile and validate successful image creation
• [ ] Test docker-compose.yml by spinning up container and verifying main.py can be invoked
• [ ] Add smoke test: verify config/ and output/ directories exist and app accepts --help
• [ ] Document Docker testing instructions in doc/CHANGELOG.md or new doc/DOCKER.md

Add doc/API_REFERENCE.md documenting available commands and their parameters

doc/COMMANDS.md exists but is referenced in file structure without visibility of its contents. Given the interactive shell nature (src/hikercli.py), users need clear parameter docs for each OSINT command. The existing COMMANDS.md likely needs expansion with examples and command reference organized by category.

• [ ] Review existing doc/COMMANDS.md and identify gaps in parameter documentation
• [ ] Add structured command reference with: command name, description, required/optional parameters, example usage, and output format
• [ ] Document all methods exposed via the shell from src/Osintgram.py (e.g., profile lookup, follower scraping, geolocation features using geopy)
• [ ] Add troubleshooting section covering common instagram-private-api errors and rate limiting
• [ ] Link API_REFERENCE.md from README.md in relevant section

• Add unit tests for src/Osintgram.py methods (info, followers, hashtags, etc.): Create tests/test_osintgram.py mocking instagram-private-api responses to catch regressions early
• Document challenge_required workaround in FAQ: The README acknowledges the Instagram challenge but offers no recovery steps; add a troubleshooting section in doc/COMMANDS.md with manual browser-based challenge resolution flow
• Add config/credentials.ini.sample template: Users see file-not-found errors; create a .sample with placeholder [instagram] section and username/password fields to reduce onboarding friction

• Critical · Outdated and Vulnerable Dependencies — requirements.txt, docker_reqs.txt. The project uses severely outdated dependencies with known vulnerabilities. Specifically: requests-toolbelt==0.9.1 (released 2018, multiple CVEs), instagram-private-api==1.6.0 (outdated and unmaintained), and hikerapi==1.7.1. These packages contain known security vulnerabilities including authentication bypass, data exposure, and injection attacks. Fix: Update all dependencies to their latest stable versions. Run 'pip-audit' or 'safety check' to identify specific CVEs. Replace unmaintained packages (instagram-private-api) with actively maintained alternatives or implement direct API calls with proper authentication.
• High · Plaintext Credentials Configuration Files — config/credentials.ini, config/settings.json. The project includes config/credentials.ini in the repository structure, which is typically used to store Instagram credentials and API tokens. If credentials are stored in plaintext, they could be exposed via version control history, Docker images, or container volumes. Fix: Never commit credentials to version control. Use environment variables or secrets management (Docker secrets, HashiCorp Vault). Add credentials.ini to .gitignore. Document the expected configuration format in a .example file instead.
• High · Insecure Credential Storage in Docker Build — docker-compose.yml, Dockerfile. The Dockerfile and docker-compose.yml mount ./output as a volume without encryption. If credentials.ini is accessed or modified during runtime, they could be exposed. Additionally, the application may write sensitive data (tokens, session info) to the output folder. Fix: Use Docker secrets for sensitive data instead of mounting plaintext credential files. Implement proper access controls on the output volume. Consider using read-only mounts where appropriate. Document which files should never be included in output.
• High · Insufficient Input Validation Risk — src/Osintgram.py, main.py (likely). As an OSINT tool that takes Instagram usernames as input and performs reconnaissance, there is a high risk of injection attacks (OS command injection, API injection, data injection) if user input is not properly validated. The tool appears to interact with Instagram API which may be vulnerable to parameter manipulation. Fix: Implement strict input validation for all user-supplied data (Instagram usernames, search parameters). Use allowlists for acceptable characters. Sanitize all inputs before passing to external APIs or system commands. Use parameterized API requests.
• High · Deprecated Python Version and Base Image — Dockerfile (FROM python:3.9.2-alpine3.13). The Dockerfile uses Python 3.9.2-alpine3.13 from 2021. Python 3.9 reached end-of-life in October 2022. The Alpine 3.13 base image (2021) is extremely outdated and lacks critical security patches for system libraries. Fix: Upgrade to Python 3.12 or 3.13 with a recent Alpine base image (Alpine 3.19 or later). Update: 'FROM python:3.13-alpine3.19'. Review and update all system packages (apk add) to current versions.
• Medium · Lack of HTTPS/TLS Configuration — requirements.txt, src/ (likely API calls). The tool uses requests library and interacts with Instagram APIs. There is no visible configuration for SSL/TLS certificate validation, proxy settings, or secure communication protocols, which could lead to man-in-the-middle attacks. Fix: Ensure all HTTP requests use HTTPS with certificate validation enabled. Use requests library's verify=True (default, but verify explicitly). Implement certificate pinning for Instagram API endpoints if applicable. Document required TLS 1.2+ enforcement.
• Medium · Missing Security Headers and Rate Limiting — main.py, src/hikercli.py (likely). The interactive shell application lacks visible rate limiting, account lockout protections, or abuse prevention mechanisms. Combined with OSINT capabilities, this could facilitate credential brute-forcing or API abuse against Instagram accounts. Fix: Implement rate limiting on API requests. Add exponential backoff for failed attempts. Include logging of all account access attempts. Document responsible use guidelines. Consider implementing request throttling to avoid Instagram API blocks.
• Medium · Inadequate Logging and Audit Trail — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.