Metadata-Version: 2.4
Name: maltego
Version: 18.303.201
Summary: An original, modular OSINT and graph analysis platform for authorized research.
Author: AltayHR
License-Expression: MIT
Project-URL: Homepage, https://github.com/AltayHR/maltego
Project-URL: Repository, https://github.com/AltayHR/maltego
Project-URL: Issues, https://github.com/AltayHR/maltego/issues
Project-URL: Community, https://turkhackteam.org/
Keywords: osint,link-analysis,graph,cybersecurity,threat-intelligence,termux
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# Maltego

> An original Python toolkit for authorized OSINT, investigation graphs, and
> link analysis.

[![PyPI](https://img.shields.io/pypi/v/maltego.svg)](https://pypi.org/project/maltego/)
[![Python](https://img.shields.io/pypi/pyversions/maltego.svg)](https://pypi.org/project/maltego/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

![Maltego Intelligence Graph Analysis](https://raw.githubusercontent.com/AltayHR/maltego/main/docs/assets/maltego-intelligence-banner.png)

## Overview

Maltego is an original, modular Python project for building investigation
graphs from user-supplied entities and safe, public-source transforms. It is
designed for Linux, Termux, headless environments, and offline graph work.
The project is inspired by the general problem space of graph-based
investigation tools; it is **not** the official Maltego product and is not
developed by or affiliated with its trademark owner.

![Maltego OSINT terminal](https://raw.githubusercontent.com/AltayHR/maltego/main/docs/assets/maltego-osint-terminal.png)

## Current status

Version `18.303.201` contains a working dependency-free core: normalized
entities, relationships, an in-memory graph engine, SQLite project storage,
JSON/CSV/GraphML export, JSON import, two local-safe transforms, provider
registry metadata, diagnostics, analytics, and a first-class CLI. Advanced
network providers, interactive shell features, GUI visualization, machines,
and external plugin execution are intentionally marked planned until their
security and compatibility contracts are implemented.

## Features

### Available

- Entity and relationship models with provenance, confidence, tags, and metadata
- Directed/undirected graph links, BFS, DFS, shortest path, components, and degree centrality
- Isolated SQLite investigation projects with an active-project workflow
- JSON, CSV, and GraphML graph export; JSON graph import
- Local URL parsing and opt-in DNS resolution transforms
- Offline mode that continues to support local project and graph operations
- Provider registry with explicit enabled/planned states
- `doctor`, `security check`, `analyze`, and `benchmark` commands
- Python 3.10+ and standard-library runtime dependencies

### Planned

- Additional RDAP, certificate, repository, and geolocation adapters
- Machine/workflow orchestration with retries, caching, and cancellation
- Interactive shell completion and a visual graph interface
- External plugin SDK and permission enforcement
- HTML/Markdown/PDF/XLSX reporting

## Architecture

```text
CLI
 ├── Project manager ── SQLite ProjectStore
 ├── Graph engine ──── Entity + Relationship models
 ├── Transform registry
 ├── Provider registry
 └── Import/export adapters
```

The runtime has no mandatory third-party dependencies. Network-capable
transforms are explicit operations and can be disabled with `--offline`.
Secrets for future providers are read from environment variables; they are
never stored in graph records or printed.

## Installation

Once the package is available on PyPI:

```bash
python -m pip install --upgrade pip
python -m pip install maltego
maltego --version
maltego doctor
```

For a source checkout:

```bash
python -m pip install -e .
```

## Termux Installation

```bash
pkg update
pkg upgrade
pkg install python git
python -m pip install --upgrade pip
python -m pip install maltego
maltego doctor
```

The core CLI, SQLite storage, graph operations, JSON/CSV/GraphML exchange,
and offline mode do not require a desktop GUI. Commands that need network
access report an explicit error when `--offline` is active.

## Linux Installation

```bash
python3 --version  # Python 3.10 or newer
python3 -m pip install maltego
maltego doctor
```

## Replit Development

```bash
python -m pip install -r requirements-dev.txt
python -m pytest
python -m build
python -m twine check dist/*
```

No Replit secret is required to run the application. `PYPI_API_TOKEN` is only
used by a release process and must never be placed in source code, README
files, or logs.

## Quick Start

```bash
maltego project create demo
maltego entity add domain example.com
maltego entity add url https://example.com/about
maltego transform run url_parts https://example.com/about --type url
maltego graph show
maltego analyze
maltego graph export demo.graphml
```

The project is stored under `~/.maltego/projects/` by default. Set
`MALTEGO_HOME` to choose another location.

## CLI

```text
maltego [--offline] [--debug] [--no-animation] <command>

project create|open|list
entity add <type> <value>
graph show|export|import
transform list|run
providers
plugins
machines
doctor
config show|validate
security check
analyze
system
benchmark
shell
```

The normal CLI avoids tracebacks and reports actionable errors. `--debug`
re-raises unexpected exceptions for development diagnosis. The banner is
shown only in TTY sessions; non-TTY and CI output stays machine-readable.

## Graph Engine

The graph engine stores entities as nodes and relationships as edges. It
supports node de-duplication, neighborhood lookup, BFS, DFS, shortest paths,
connected components, relationship counts, and degree centrality. It is
dependency-free and can be used directly:

```python
from maltego.graph import Graph
from maltego.models import Entity, Relationship

graph = Graph()
domain = graph.add_entity(Entity("domain", "example.com"))
ip = graph.add_entity(Entity("ip", "192.0.2.1"))
graph.add_relationship(Relationship(domain.id, ip.id, "resolves_to"))
```

## Entities

Any normalized string type can be represented, including `domain`, `ip`,
`url`, `email`, `username`, `organization`, `certificate`, `repository`, and
custom types. Each entity records an ID, value, label, description, metadata,
source, confidence, timestamps, tags, and properties.

## Relationships

Relationships carry endpoint IDs, a normalized kind, direction, confidence,
source, metadata, and timestamp. Examples include `resolves_to`, `contains`,
`uses_certificate`, `links_to`, and `related_to`.

## Transforms

Transforms receive an entity and return normalized entities plus
relationships. The current registry includes:

- `url_parts`: local URL/hostname parsing, no network access
- `dns_resolution`: local system resolver, disabled by `--offline`

```bash
maltego transform list
maltego transform run url_parts https://example.com --type url
maltego --offline transform run dns_resolution example.com --type domain
```

## Machines

Machine/workflow orchestration is planned. The CLI currently reports an empty
machine registry rather than pretending that workflows are available.

## Providers

The provider registry currently exposes a local DNS provider as enabled and
RDAP, GitHub, and certificate adapter boundaries as planned. API keys are not
needed for the current core.

```bash
maltego providers
```

## Plugins

External plugin loading is planned. This release deliberately does not
execute arbitrary third-party code. A future plugin SDK will require explicit
permissions for network, filesystem, database, external API, and process
execution access.

## Investigation Projects

Each project is isolated in its own SQLite database. The active project path
is recorded in `MALTEGO_HOME/active_project`, and the graph itself remains
portable through export formats.

## Graph Analytics

```bash
maltego analyze
```

The current summary reports entity count, relationship count, connected
components, and maximum degree centrality. More advanced centrality and
community algorithms are planned.

## Import / Export

Supported export suffixes are `.json`, `.csv`, and `.graphml`. JSON import is
available now; GraphML and CSV import are planned.

```bash
maltego graph export investigation.json
maltego graph export investigation.graphml
maltego graph export investigation.csv
maltego graph import investigation.json
```

## Evidence & Sources

Entity and relationship models include `source`, `confidence`, metadata, and
timestamps. A complete evidence timeline and raw-reference store are planned;
the current release does not claim to provide forensic evidence management.

## Configuration

```bash
export MALTEGO_HOME="$HOME/.local/share/maltego"
maltego config show
maltego config validate
```

## API Keys and Environment Variables

The current release has no required API keys. Future provider credentials
should be supplied through environment variables or Replit Secrets, for
example `GITHUB_TOKEN` or `VIRUSTOTAL_API_KEY`. Values must never be pasted
into issues, README files, graph metadata, or logs. `PYPI_API_TOKEN` is a
release-only secret and is not read by the runtime.

## Examples

The commands in Quick Start are executable against a local project. The
`examples/` directory will grow with the public API as the transform,
machine, and plugin contracts stabilize.

## Developer Guide

```bash
python -m pip install -r requirements-dev.txt
python -m pytest
ruff check .
mypy src/
python -m build
python -m twine check dist/*
```

See [architecture](docs/architecture.md), [CLI](docs/cli.md), and
[installation](docs/installation.md) for the current contracts.

## Plugin Development

The public registry interfaces are intentionally small. Until the permission
model is released, add-on code should not be installed as an executable
plugin. See [the plugin design notes](docs/plugins.md).

## Testing

The test suite covers graph traversal, de-duplication, SQLite round-trips,
URL transform behavior, and the CLI project flow. Run:

```bash
python -m pytest
python -m pytest --cov=maltego
```

Coverage percentages are not published here because no hosted CI coverage
service is configured yet.

## Security

Use this project only for authorized investigations, defensive research,
education, and public-source analysis. It does not automate exploitation,
credential theft, password cracking, or unauthorized access. Report security
issues privately according to [SECURITY.md](SECURITY.md).

## Performance

The core uses indexed SQLite tables, incremental graph updates, and bounded
local transform timeouts. Large-graph pagination, caching, and lazy visual
rendering are planned.

## Troubleshooting

- `No active project`: run `maltego project create <name>`.
- `DNS resolution is unavailable in offline mode`: remove `--offline` only
  when authorized network access is available.
- `Project not found`: check `MALTEGO_HOME` and run `maltego project list`.
- For a detailed development traceback, add `--debug`.

## FAQ

### Is this the official Maltego application?

No. This is an independent, original project for the same broad class of
authorized OSINT and graph-analysis workflows.

### Does it work offline?

Yes. Project management, graph editing, analytics, export, import, and
diagnostics work without network access. Network transforms do not.

### Is an API key required?

Not for the current core release.

### Can it run on Termux?

The dependency-free CLI and SQLite core are designed for Linux and Termux.
Desktop GUI features are not part of the current release.

## Roadmap

- [x] Core graph and entity model
- [x] SQLite project storage
- [x] CLI project/entity/graph flow
- [x] JSON, CSV, and GraphML export
- [x] Offline mode and diagnostics
- [ ] RDAP, certificate, and repository providers
- [ ] Machine/workflow engine
- [ ] Evidence and report generation
- [ ] Secure plugin SDK and permissions
- [ ] Interactive shell and visual graph interface

## Contributing

Contributions should preserve the original implementation, explicit security
boundaries, type hints, and truthful documentation. Read
[CONTRIBUTING.md](CONTRIBUTING.md) before opening a change.

## Developer / Community / Project Links

- Developer / Contact: [Telegram @AltayHR](https://t.me/AltayHR)
- Community: [TurkHackTeam](https://turkhackteam.org/)
- Repository: [github.com/AltayHR/maltego](https://github.com/AltayHR/maltego)

## License

Released under the [MIT License](LICENSE). This project is independent and
does not include proprietary code or assets from any third-party product.

## Disclaimer

The project is provided for lawful, authorized research and education. You
are responsible for complying with applicable laws, contracts, terms of
service, and privacy obligations. No affiliation with or endorsement by the
official Maltego product or its trademark owner is implied.
